teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/domain/participants.py

@@ -0,0 +1,292 @@
+"""Pure participant categorisation functions.
+
+Parses attendance data from Teams Event/Call ``<partlist>`` XML,
+Tracking/RSVP data from the Details tab, and combines it with roster
+and speaker data to build categorised
+:class:`~teams_transcripts.domain.models.MeetingParticipants`.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.
+"""
+
+from __future__ import annotations
+
+import re
+
+from teams_transcripts.domain.models import MeetingParticipants, RosterMember
+
+
+def parse_partlist_xml(content: str) -> list[dict]:
+    """Parse ``<partlist>`` XML from an Event/Call message content string.
+
+    The ``<partlist>`` element is embedded in the ``content`` field of
+    Teams Event/Call messages (``messageType == "Event/Call"``).  Each
+    ``<part>`` child represents a call participant with their MRI
+    identity, display name, and duration in seconds.
+
+    Note: Teams may declare a ``count`` attribute larger than the actual
+    number of ``<part>`` elements (the XML is truncated server-side).
+
+    Args:
+        content: Raw HTML/XML content string from an Event/Call message.
+
+    Returns:
+        List of dicts, each with keys:
+            - ``identity`` (str): Full MRI string (e.g. ``"8:orgid:abc-123"``).
+            - ``display_name`` (str): Participant display name.
+            - ``duration_seconds`` (int): Duration in the call in seconds.
+    """
+    # Find the <partlist>...</partlist> block
+    partlist_match = re.search(r"<partlist[^>]*>(.*?)</partlist>", content, re.DOTALL)
+    if not partlist_match:
+        return []
+
+    partlist_body = partlist_match.group(1)
+    if not partlist_body.strip():
+        return []
+
+    # Extract each <part> element
+    parts: list[dict] = []
+    for part_match in re.finditer(
+        r'<part\s+identity="([^"]*)">(.*?)</part>',
+        partlist_body,
+        re.DOTALL,
+    ):
+        identity = part_match.group(1)
+        part_body = part_match.group(2)
+
+        # Extract <displayName>
+        dn_match = re.search(r"<displayName>(.*?)</displayName>", part_body)
+        display_name = _decode_xml_entities(dn_match.group(1)) if dn_match else ""
+
+        # Extract <duration>
+        dur_match = re.search(r"<duration>(\d+)</duration>", part_body)
+        duration = int(dur_match.group(1)) if dur_match else 0
+
+        parts.append(
+            {
+                "identity": identity,
+                "display_name": display_name,
+                "duration_seconds": duration,
+            }
+        )
+
+    return parts
+
+
+# ---------------------------------------------------------------------------
+# Tracking/RSVP parsing
+# ---------------------------------------------------------------------------
+
+# Known RSVP status values in the Teams Tracking panel aria-labels.
+# The regex captures the status word immediately before the comma+position
+# suffix (e.g. ", 1 of 15, ...").
+_TRACKING_STATUSES = {"Accepted", "Tentative", "Declined", "None", "Organizer"}
+
+# Pattern: "<Name> <Status>, <N> of <M>, in a list of <M> items, Dialogue Pop-up Button"
+# The status word is one of the known values.  The name may contain
+# parentheses, hyphens, etc.
+_TRACKING_LABEL_RE = re.compile(
+    r"^(.+?)\s+(Accepted|Tentative|Declined|None|Organizer)"
+    r",\s+\d+\s+of\s+\d+,\s+in a list of \d+ items",
+)
+
+
+def parse_tracking_entries(aria_labels: list[str]) -> list[dict]:
+    """Parse aria-label strings from the Teams Tracking panel.
+
+    Each label has the format:
+        ``"Name Status, N of M, in a list of M items, Dialogue Pop-up Button"``
+
+    where *Status* is one of ``Accepted``, ``Tentative``, ``Declined``,
+    ``None`` (no response), or ``Organizer``.
+
+    Args:
+        aria_labels: Raw aria-label strings collected from the Tracking
+            panel list items.
+
+    Returns:
+        List of dicts, each with keys:
+            - ``name`` (str): Display name.
+            - ``rsvp_status`` (str): Normalised status (lowercase).
+    """
+    entries: list[dict] = []
+    for label in aria_labels:
+        m = _TRACKING_LABEL_RE.match(label)
+        if not m:
+            continue
+        name = m.group(1).strip()
+        status = m.group(2).lower()
+        entries.append({"name": name, "rsvp_status": status})
+    return entries
+
+
+def enrich_with_rsvp(
+    members: list[RosterMember],
+    tracking: list[dict],
+) -> list[RosterMember]:
+    """Enrich roster members with RSVP status from tracking data.
+
+    Matches tracking entries to members by normalised display name
+    (case-insensitive, whitespace-collapsed).  Unmatched tracking
+    entries (e.g. distribution lists) are silently ignored.  Unmatched
+    members retain an empty ``rsvp_status``.
+
+    Since :class:`RosterMember` is frozen, new instances are created
+    for members whose status changes.
+
+    Args:
+        members: Existing roster members (may have empty ``rsvp_status``).
+        tracking: Parsed tracking entries from :func:`parse_tracking_entries`.
+
+    Returns:
+        New list of :class:`RosterMember` with ``rsvp_status`` populated
+        where a match was found.
+    """
+    if not tracking:
+        return list(members)
+
+    # Build lookup: normalised name -> rsvp_status
+    status_by_name: dict[str, str] = {}
+    for entry in tracking:
+        key = _normalise_name(entry["name"])
+        status_by_name[key] = entry["rsvp_status"]
+
+    result: list[RosterMember] = []
+    for m in members:
+        key = _normalise_name(m.name)
+        status = status_by_name.get(key, "")
+        if status and status != m.rsvp_status:
+            result.append(
+                RosterMember(
+                    name=m.name,
+                    email=m.email,
+                    object_id=m.object_id,
+                    role=m.role,
+                    rsvp_status=status,
+                )
+            )
+        else:
+            result.append(m)
+    return result
+
+
+def build_meeting_participants(
+    *,
+    all_members: list[RosterMember],
+    speaker_map: dict[str, str],
+    attendance: list[dict],
+    organizer_id: str,
+    tracking: list[dict] | None = None,
+) -> MeetingParticipants:
+    """Build categorised participant lists from all data sources.
+
+    Cross-references the full roster (from the participant popover),
+    the Recap speaker mapping, the Event/Call attendance list, and
+    optionally the Tracking/RSVP data to produce four categories:
+    organiser, invited, speakers, attendees.
+
+    When ``tracking`` is provided, all members are enriched with RSVP
+    status before categorisation, so organiser, speakers, and attendees
+    also carry the status.
+
+    Args:
+        all_members: Complete roster from the participant popover.
+            Each member has ``object_id`` (bare GUID), ``name``, ``email``.
+        speaker_map: GUID-to-displayName mapping from the Recap
+            Speakers tab.
+        attendance: List of attendance dicts from :func:`parse_partlist_xml`.
+            Each has ``identity`` (MRI), ``display_name``, ``duration_seconds``.
+        organizer_id: Bare GUID of the meeting organiser (from
+            ``meetingInformation.organizerId``), or empty string.
+        tracking: Optional list of tracking dicts from
+            :func:`parse_tracking_entries`.  Each has ``name`` and
+            ``rsvp_status``.
+
+    Returns:
+        :class:`MeetingParticipants` with all four categories populated.
+    """
+    # Enrich members with RSVP status before categorisation
+    enriched = enrich_with_rsvp(all_members, tracking) if tracking else list(all_members)
+
+    # Index enriched members by objectId for fast lookup
+    members_by_id: dict[str, RosterMember] = {}
+    for m in enriched:
+        if m.object_id:
+            members_by_id[m.object_id] = m
+
+    # Organiser
+    organiser: list[RosterMember] = []
+    if organizer_id and organizer_id in members_by_id:
+        organiser = [members_by_id[organizer_id]]
+
+    # Invited = all enriched members, sorted by name
+    invited = sorted(enriched, key=lambda m: m.name.lower())
+
+    # Speakers = roster members whose objectId is in the speaker_map
+    speakers = [members_by_id[guid] for guid in speaker_map if guid in members_by_id]
+    speakers.sort(key=lambda m: m.name.lower())
+
+    # Attendees = roster members whose objectId matches an attendance
+    # identity MRI.  Bots (identity starting with "28:") are excluded.
+    # Deduplicate by objectId (multiple partlists may list the same person).
+    seen_attendee_ids: set[str] = set()
+    attendees: list[RosterMember] = []
+    for att in attendance:
+        identity = att["identity"]
+        # Skip bots
+        if identity.startswith("28:"):
+            continue
+        # Extract bare GUID from MRI "8:orgid:{guid}"
+        guid = _extract_guid_from_mri(identity)
+        if not guid or guid in seen_attendee_ids:
+            continue
+        if guid in members_by_id:
+            attendees.append(members_by_id[guid])
+            seen_attendee_ids.add(guid)
+    attendees.sort(key=lambda m: m.name.lower())
+
+    return MeetingParticipants(
+        organiser=organiser,
+        invited=invited,
+        speakers=speakers,
+        attendees=attendees,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_guid_from_mri(mri: str) -> str:
+    """Extract the bare GUID from a Teams MRI string.
+
+    MRI format: ``"8:orgid:{guid}"`` or ``"28:{bot-id}"``.
+    Returns the last colon-separated segment, or the original string
+    if no colons are present.
+    """
+    if ":" in mri:
+        return mri.split(":")[-1]
+    return mri
+
+
+def _normalise_name(name: str) -> str:
+    """Normalise a display name for case-insensitive, whitespace-tolerant matching.
+
+    Lowercases, strips leading/trailing whitespace, and collapses internal
+    runs of whitespace to a single space.
+    """
+    return " ".join(name.lower().split())
+
+
+def _decode_xml_entities(text: str) -> str:
+    """Decode common XML entities in a string.
+
+    Handles ``&amp;``, ``&lt;``, ``&gt;``, ``&quot;``, ``&apos;``.
+    """
+    text = text.replace("&amp;", "&")
+    text = text.replace("&lt;", "<")
+    text = text.replace("&gt;", ">")
+    text = text.replace("&quot;", '"')
+    return text.replace("&apos;", "'")

teams_transcripts/domain/scoring.py

@@ -0,0 +1,106 @@
+"""Pure search result scoring and occurrence matching functions.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+
+
+def score_search_result(meeting_name: str, result_text: str) -> float:
+    """Score a search result against the meeting name using word overlap.
+
+    The algorithm:
+    1. Tokenise both strings into lowercase word sets.
+    2. Count exact word overlaps.
+    3. For each meeting-name word not in the exact overlap, check if it
+       appears as a substring of the result text (handles concatenated
+       words like ``"CallAdrian"``).
+    4. Subtract 0.5 if the result text starts with a ``Name:`` pattern
+       (indicating a personal message rather than a meeting entry).
+
+    Args:
+        meeting_name: The meeting search string.
+        result_text: The text content of a search result.
+
+    Returns:
+        Numeric score (higher is better).
+    """
+    name_words = set(re.findall(r"\w+", meeting_name.lower()))
+    result_text_lower = result_text.lower()
+    result_words = set(re.findall(r"\w+", result_text_lower))
+
+    # Exact word overlap
+    overlap = len(name_words & result_words)
+
+    # Substring match for words not in exact overlap
+    for nw in name_words - result_words:
+        if nw in result_text_lower:
+            overlap += 1
+
+    # Tiebreaker: penalise personal message results
+    score = float(overlap)
+    if re.match(r"^[A-Z][a-z]+:", result_text):
+        score -= 0.5
+
+    return score
+
+
+def best_result_index(meeting_name: str, results: list[str]) -> int:
+    """Return the index of the best-scoring search result.
+
+    Ties are broken by preferring the earlier (lower-index) result.
+
+    Args:
+        meeting_name: The meeting search string.
+        results: List of search result text strings.
+
+    Returns:
+        Zero-based index of the best result.
+    """
+    best_idx, best_score = 0, 0.0
+    for i, text in enumerate(results):
+        s = score_search_result(meeting_name, text)
+        if s > best_score:
+            best_score = s
+            best_idx = i
+    return best_idx
+
+
+def occurrence_matches(
+    text: str,
+    target_date: str,
+    target_time: str | None,
+) -> bool:
+    """Check whether an occurrence dropdown text matches the target date/time.
+
+    The text has the form ``"22 April 2026 11:15 -  12:00"``.  The match
+    requires that the day number, month name, and year all appear in the
+    text.  If *target_time* is provided, it must appear before the dash
+    separator (i.e. it must be the start time, not the end time).
+
+    Args:
+        text: Raw occurrence dropdown text.
+        target_date: Target date as ``YYYY-MM-DD``.
+        target_time: Target time as ``HH:MM``, or ``None`` for date-only.
+
+    Returns:
+        ``True`` if the text matches the target.
+    """
+    dt = date.fromisoformat(target_date)
+    date_pattern = re.compile(
+        rf"(?<!\d){dt.day}\s+{re.escape(dt.strftime('%B'))}\s+{dt.year}(?!\d)",
+        re.IGNORECASE,
+    )
+
+    if not date_pattern.search(text):
+        return False
+    if target_time is None:
+        return True
+    sep_idx = text.find("-")
+    if sep_idx == -1:
+        return target_time in text
+    return target_time in text[:sep_idx]

teams_transcripts/domain/speakers.py

@@ -0,0 +1,130 @@
+"""Pure speaker resolution and mapping functions.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def resolve_chat_author(
+    from_user_id: str,
+    im_display_name: str,
+    speaker_map: dict[str, str] | None,
+) -> str:
+    """Resolve a chat message author name using the speaker mapping.
+
+    Extracts the bare GUID from ``fromUserId`` (format ``8:orgid:{GUID}``)
+    and checks the speaker_map for a cleaner display name.  Falls back to
+    ``imDisplayName`` from the message props, then to ``"Unknown"``.
+
+    Args:
+        from_user_id: Teams user ID string (e.g. ``"8:orgid:abc-123"``).
+        im_display_name: Fallback display name from the message.
+        speaker_map: Mapping of GUID to display name, or ``None``.
+
+    Returns:
+        Best available human-readable name.
+    """
+    if speaker_map and from_user_id and ":" in from_user_id:
+        guid = from_user_id.split(":")[-1]
+        mapped = speaker_map.get(guid)
+        if mapped:
+            return mapped
+
+    return im_display_name or "Unknown"
+
+
+def apply_speaker_mapping(content: str, speaker_map: dict[str, str]) -> str:
+    """Replace speaker names in VTT content using the Recap speaker mapping.
+
+    Native VTT downloads (Approach A) contain speaker names in
+    ``<v SPEAKER_NAME>`` tags.  This function matches each VTT speaker
+    name to a Recap display name and replaces it.
+
+    The mapping keys are GUIDs, but VTT files don't contain GUIDs --
+    they contain display names.  Matching is done by:
+
+    1. ``@N`` pattern: Recap shows ``Speaker N``.
+    2. Substring match: VTT has ``v-Gabor Veres (Metosin)``, Recap has
+       ``Gabor Veres``.  The Recap name is a substring of the VTT name.
+       The longest matching Recap name wins.
+    3. Exact match: names are already identical -- no replacement needed.
+
+    Args:
+        content: Raw VTT file content.
+        speaker_map: Mapping of GUID to Recap display name.
+
+    Returns:
+        VTT content with speaker names replaced.
+    """
+    # Extract all unique speaker names from the VTT.
+    vtt_names = set(re.findall(r"<v ([^>]+)>", content))
+    recap_names = set(speaker_map.values())
+
+    replacements: dict[str, str] = {}  # old_vtt_name -> recap_name
+
+    for vtt_name in vtt_names:
+        if vtt_name in recap_names:
+            # Already matches a Recap name exactly -- no change needed.
+            continue
+
+        # 1. @N pattern: look for "Speaker N" in Recap names.
+        at_match = re.match(r"^@(\d+)$", vtt_name)
+        if at_match:
+            speaker_label = f"Speaker {at_match.group(1)}"
+            if speaker_label in recap_names:
+                replacements[vtt_name] = speaker_label
+                continue
+
+        # 2. Substring match: a Recap name is contained in the VTT name.
+        #    Pick the longest matching Recap name to avoid false positives.
+        best_match = None
+        best_len = 0
+        for recap_name in recap_names:
+            if recap_name in vtt_name and len(recap_name) > best_len:
+                best_match = recap_name
+                best_len = len(recap_name)
+        if best_match:
+            replacements[vtt_name] = best_match
+
+    if not replacements:
+        return content
+
+    for old_name, new_name in replacements.items():
+        old_tag = f"<v {old_name}>"
+        new_tag = f"<v {new_name}>"
+        content = content.replace(old_tag, new_tag)
+
+    return content
+
+
+def build_speaker_map_from_roster(
+    roster_members: list[dict],
+    speaker_map: dict[str, str] | None,
+) -> dict[str, str]:
+    """Build a combined GUID-to-name map from the roster and speaker_map.
+
+    The roster covers all chat members (including non-speakers), which
+    lets us resolve reaction authors and chat authors that the speaker_map
+    alone cannot.  Speaker map entries take priority (Recap canonical names).
+
+    Args:
+        roster_members: List of roster member dicts with ``"objectId"``
+            and ``"name"`` keys.
+        speaker_map: Existing GUID-to-name mapping from Recap, or ``None``.
+
+    Returns:
+        Combined GUID-to-name mapping.
+    """
+    member_map: dict[str, str] = {}
+    for rm in roster_members:
+        oid = rm.get("objectId", "")
+        if oid and rm.get("name"):
+            member_map[oid] = rm["name"]
+    # Speaker map entries take priority (Recap canonical names).
+    if speaker_map:
+        member_map.update(speaker_map)
+    return member_map