talkTime

handler.py

@@ -26,6 +26,32 @@ REASONING_MODEL = 'ddemszky/student-reasoning'
 QUESTION_MODEL = 'ddemszky/question-detection'
 FOCUSING_QUESTION_MODEL = 'ddemszky/focusing-questions'
 
+# Speaker label the diarizer gives to unattributed segments such as [crosstalk].
+UNKNOWN_SPEAKER = 'unknown'
+
+# Column names in the CSV transcript export, mapped to Utterance arguments.
+CSV_FIELD_ALIASES = {
+    'speaker_uid': 'speaker',
+    'utterance_text': 'text',
+    'utterance_index': 'uid',
+    'start_time': 'starttime',
+    'end_time': 'endtime',
+}
+
+
+def normalize_utterance_fields(utt):
+    normalized = dict(utt)
+    for alias, name in CSV_FIELD_ALIASES.items():
+        if alias in normalized:
+            normalized.setdefault(name, normalized.pop(alias))
+    return normalized
+
+
+def to_float(value):
+    if value is None or value == '':
+        return None
+    return float(value)
+
 
 class Utterance:
     def __init__(self, speaker, text, uid=None,
@@ -33,6 +59,8 @@ class Utterance:
         self.speaker = speaker
         self.text = text
         self.uid = uid
+        starttime = to_float(starttime)
+        endtime = to_float(endtime)
         self.starttime = starttime
         self.endtime = endtime
         self.transcript = weakref.ref(transcript) if transcript else None
@@ -64,6 +92,12 @@ class Utterance:
     def get_num_words(self):
         return get_num_words(self.text)
 
+    def get_duration(self):
+        """Seconds spoken, or None if the utterance has no timestamps."""
+        if self.starttime is None or self.endtime is None:
+            return None
+        return max(0.0, self.endtime - self.starttime)
+
     def to_dict(self):
         return {
             'speaker': self.speaker,
@@ -102,8 +136,12 @@ class Utterance:
             # On/off-task classification: a measure in its own right, alongside
             # vocabulary. None means not classified (teacher utterance or empty text).
             'onTask': None if self.on_task is None else self.on_task.get('label') == ON_TASK_LABEL,
+            # Seconds when every utterance has timestamps, word counts otherwise
+            # (see Transcript.calculate_aggregate_word_count). duration and
+            # wordCount always have a single unit.
             'unitMeasure': self.unit_measure,
             'aggregateUnitMeasure': self.aggregate_unit_measure,
+            'duration': None if self.get_duration() is None else round(self.get_duration(), 2),
             'wordCount': self.word_count,
             'numMathTerms': self.num_math_terms,
             'mathTerms': self.math_terms,
@@ -148,7 +186,7 @@ class Transcript:
 
     def get_talk_distribution_and_length(self, uptake_speaker):
         if ((uptake_speaker is None)):
-            return None
+            return None, None
         teacher_words = 0
         teacher_utt_count = 0
         student_words = 0
@@ -162,7 +200,7 @@ class Transcript:
                 utt.role = 'student'
                 student_words += utt.get_num_words()
                 student_utt_count += 1
-        if teacher_words + student_words > 0:         
+        if teacher_words + student_words > 0:
             teacher_percentage = round(
                 (teacher_words / (teacher_words + student_words)) * 100)
             student_percentage = 100 - teacher_percentage
@@ -172,6 +210,81 @@ class Transcript:
         avg_student_length = student_words / student_utt_count if student_utt_count > 0 else 0
         return {'teacher': teacher_percentage, 'student': student_percentage}, {'teacher': avg_teacher_length, 'student': avg_student_length}
 
+    def get_talk_time_stats(self, uptake_speaker):
+        """
+        Talk measured in seconds (endtime - starttime). Utterances without
+        timestamps are skipped and reported as untimed. Returns None when no
+        utterance has timestamps.
+
+        Exact duplicate utterances (same speaker, times and text) are counted
+        once. The teacher/student figures are None when there is no teacher
+        speaker, and leave out the unknown speaker, which cannot be attributed
+        to either role; it is still listed in the per-speaker breakdown.
+        """
+        timed = [utt for utt in self.utterances if utt.get_duration() is not None]
+        if not timed:
+            return None
+        totals = {'teacher': 0.0, 'student': 0.0}
+        counts = {'teacher': 0, 'student': 0}
+        by_speaker = {}
+        seen = set()
+        for utt in self.utterances:
+            duration = utt.get_duration()
+            if duration is not None:
+                key = (utt.speaker, utt.starttime, utt.endtime, utt.text)
+                if key in seen:
+                    continue
+                seen.add(key)
+            if uptake_speaker is None:
+                role = None
+            else:
+                role = 'teacher' if utt.speaker == uptake_speaker else 'student'
+            speaker_stats = by_speaker.setdefault(utt.speaker, {
+                'role': role, 'seconds': 0.0, 'timedUtterances': 0,
+                'untimedUtterances': 0, 'confidences': []})
+            confidence = to_float(utt.props.get('speaker_id_confidence'))
+            if confidence is not None:
+                speaker_stats['confidences'].append(confidence)
+            if duration is None:
+                speaker_stats['untimedUtterances'] += 1
+                continue
+            speaker_stats['seconds'] += duration
+            speaker_stats['timedUtterances'] += 1
+            if role is None or (utt.speaker == UNKNOWN_SPEAKER and role == 'student'):
+                continue
+            totals[role] += duration
+            counts[role] += 1
+
+        for speaker_stats in by_speaker.values():
+            confidences = speaker_stats.pop('confidences')
+            speaker_stats['seconds'] = round(speaker_stats['seconds'], 2)
+            speaker_stats['avgConfidence'] = (
+                round(sum(confidences) / len(confidences), 4) if confidences else None)
+        session_start = min(utt.starttime for utt in timed)
+        session_end = max(utt.endtime for utt in timed)
+        stats = {
+            'distribution': None,
+            'length': None,
+            'total': None,
+            'sessionDuration': round(session_end - session_start, 2),
+            'untimedUtterances': len(self.utterances) - len(timed),
+            'bySpeaker': by_speaker,
+        }
+        if uptake_speaker is None:
+            return stats
+
+        talk = totals['teacher'] + totals['student']
+        if talk > 0:
+            teacher_percentage = round(totals['teacher'] / talk * 100)
+            student_percentage = 100 - teacher_percentage
+        else:
+            teacher_percentage = student_percentage = 0
+        stats['distribution'] = {'teacher': teacher_percentage, 'student': student_percentage}
+        stats['length'] = {role: round(totals[role] / counts[role], 2) if counts[role] > 0 else 0
+                           for role in totals}
+        stats['total'] = {role: round(totals[role], 2) for role in totals}
+        return stats
+
     def get_vocabulary_table(self):
         """
         Build a summary of matched vocabulary terms by utterance role.
@@ -511,7 +624,7 @@ class EndpointHandler():
 
         transcript = Transcript(filename=params.pop("filename", None))
         for utt in utterances:
-            transcript.add_utterance(Utterance(**utt))
+            transcript.add_utterance(Utterance(**normalize_utterance_fields(utt)))
 
         print("Running inference on %d examples..." % transcript.length())
         logging.set_verbosity_info()
@@ -557,6 +670,13 @@ class EndpointHandler():
         talk_dist, talk_len = transcript.get_talk_distribution_and_length(uptake_speaker)
         return_dict['talkDistribution'] = talk_dist
         return_dict['talkLength'] = talk_len
+        talk_time = transcript.get_talk_time_stats(uptake_speaker) or {}
+        return_dict['talkTimeDistribution'] = talk_time.get('distribution')
+        return_dict['talkTimeLength'] = talk_time.get('length')
+        return_dict['talkTimeTotal'] = talk_time.get('total')
+        return_dict['talkTimeBySpeaker'] = talk_time.get('bySpeaker')
+        return_dict['sessionDuration'] = talk_time.get('sessionDuration')
+        return_dict['talkTimeUntimedUtterances'] = talk_time.get('untimedUtterances')
         talk_moments = transcript.get_talk_timeline()
         return_dict['talkMoments'] = talk_moments
         word_cloud, uptake_word_cloud, teacher_general_cloud, student_general_cloud = transcript.get_word_clouds()

tests/test_talk_distribution.py

@@ -0,0 +1,130 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from handler import Transcript, Utterance, normalize_utterance_fields
+
+TEACHER = "teacher-uid"
+
+
+def build_transcript(rows):
+    transcript = Transcript()
+    for row in rows:
+        transcript.add_utterance(Utterance(**normalize_utterance_fields(row)))
+    return transcript
+
+
+def test_word_distribution_unchanged():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "one two three", "starttime": 0.0, "endtime": 1.0},
+        {"speaker": "student-uid", "text": "four", "starttime": 1.0, "endtime": 4.0},
+    ])
+    dist, length = transcript.get_talk_distribution_and_length(TEACHER)
+    assert dist == {"teacher": 75, "student": 25}
+    assert length == {"teacher": 3, "student": 1}
+
+
+def test_no_uptake_speaker_keeps_speaker_level_time():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "hi", "starttime": 0.0, "endtime": 1.0},
+        {"speaker": "s1", "text": "hello", "starttime": 1.0, "endtime": 3.0},
+    ])
+    assert transcript.get_talk_distribution_and_length(None) == (None, None)
+    stats = transcript.get_talk_time_stats(None)
+    assert stats["distribution"] is None
+    assert stats["length"] is None
+    assert stats["total"] is None
+    assert stats["sessionDuration"] == 3.0
+    assert stats["bySpeaker"]["s1"]["role"] is None
+    assert stats["bySpeaker"]["s1"]["seconds"] == 2.0
+
+
+def test_talk_time_uses_seconds():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "one two three four five six", "starttime": 10.0, "endtime": 13.0},
+        {"speaker": "s1", "text": "ok", "starttime": 13.0, "endtime": 14.0},
+        {"speaker": "s2", "text": "yes", "starttime": 14.0, "endtime": 17.0},
+    ])
+    stats = transcript.get_talk_time_stats(TEACHER)
+    # 3s teacher vs 4s student, regardless of word counts
+    assert stats["distribution"] == {"teacher": 43, "student": 57}
+    assert stats["length"] == {"teacher": 3.0, "student": 2.0}
+    assert stats["total"] == {"teacher": 3.0, "student": 4.0}
+    assert stats["sessionDuration"] == 7.0
+    assert stats["untimedUtterances"] == 0
+    assert stats["bySpeaker"]["s2"] == {
+        "role": "student", "seconds": 3.0, "timedUtterances": 1,
+        "untimedUtterances": 0, "avgConfidence": None}
+
+
+def test_untimed_utterances_skipped_and_counted():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "one", "starttime": 0.0, "endtime": 1.0},
+        {"speaker": "s1", "text": "two", "starttime": 1.0, "endtime": 4.0},
+        {"speaker": "s1", "text": "Yeah."},
+        {"speaker": "s1", "text": "Yeah."},
+    ])
+    stats = transcript.get_talk_time_stats(TEACHER)
+    assert stats["distribution"] == {"teacher": 25, "student": 75}
+    assert stats["untimedUtterances"] == 2
+    # untimed repeats are not treated as duplicates
+    assert stats["bySpeaker"]["s1"]["timedUtterances"] == 1
+    assert stats["bySpeaker"]["s1"]["untimedUtterances"] == 2
+
+
+def test_talk_time_none_when_no_timestamps():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "one"},
+        {"speaker": "s1", "text": "two"},
+    ])
+    assert transcript.get_talk_time_stats(TEACHER) is None
+
+
+def test_unknown_speaker_excluded_from_combined_but_listed():
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "hello", "starttime": 0.0, "endtime": 2.0},
+        {"speaker": "s1", "text": "hi", "starttime": 2.0, "endtime": 4.0},
+        {"speaker": "unknown", "text": "[crosstalk].", "starttime": 5.0, "endtime": 6.0},
+    ])
+    stats = transcript.get_talk_time_stats(TEACHER)
+    assert stats["distribution"] == {"teacher": 50, "student": 50}
+    assert stats["total"] == {"teacher": 2.0, "student": 2.0}
+    assert stats["bySpeaker"]["unknown"]["seconds"] == 1.0
+
+
+def test_exact_duplicates_counted_once():
+    row = {"speaker": "s1", "text": "10 times 6.", "starttime": 447.25, "endtime": 448.0}
+    transcript = build_transcript([
+        {"speaker": TEACHER, "text": "what times what?", "starttime": 446.0, "endtime": 447.0},
+        row,
+        dict(row),
+    ])
+    stats = transcript.get_talk_time_stats(TEACHER)
+    assert stats["total"]["student"] == 0.75
+    assert stats["bySpeaker"]["s1"]["timedUtterances"] == 1
+
+
+def test_csv_columns_are_mapped():
+    row = {
+        "utterance_index": "7",
+        "speaker_uid": TEACHER,
+        "start_time": "151.283",
+        "end_time": "151.646",
+        "utterance_text": "Thank you.",
+        "speaker_id_confidence": "0.95",
+    }
+    utt = Utterance(**normalize_utterance_fields(row))
+    assert utt.speaker == TEACHER
+    assert utt.text == "Thank you."
+    assert utt.uid == "7"
+    assert utt.get_duration() == pytest.approx(0.363)
+    assert utt.props == {"speaker_id_confidence": "0.95"}
+
+    transcript = Transcript()
+    transcript.add_utterance(utt)
+    assert transcript.get_talk_time_stats(TEACHER)["bySpeaker"][TEACHER]["avgConfidence"] == 0.95