teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/domain/summary.py

@@ -0,0 +1,266 @@
+"""Pure result summary and VTT verification functions.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.
+"""
+
+from __future__ import annotations
+
+import re
+import typing
+from collections import Counter
+
+from teams_transcripts.domain.timestamps import parse_meeting_times
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.domain.models import ChatMessage, MeetingParticipants, TranscriptCue
+
+
+def build_result_summary(
+    config: dict,
+    *,
+    num_parts: int = 1,
+    verification: dict | None = None,
+    chat_count: int = 0,
+    participants: MeetingParticipants | None = None,
+    chat_messages: list[ChatMessage] | None = None,
+    transcript_cues: list[TranscriptCue] | None = None,
+    include_transcript: bool = True,
+    include_chat: bool = True,
+    include_metadata: bool = True,
+) -> dict:
+    """Build a structured result summary from config and verification data.
+
+    Used for both ``--format json`` output and ``--dry-run`` summaries.
+
+    The output is composable: each component flag controls which fields
+    are included.  When all three are True (default), backward-compatible
+    schema is produced.
+
+    When ``participants`` is provided and ``include_metadata`` is True,
+    the summary uses categorised fields (``organiser``, ``invited``,
+    ``speakers_list``, ``attendees``).
+
+    When ``chat_messages`` is provided and ``include_chat`` is True,
+    the full ``chat`` array is included.  When all components are
+    included, ``chat_messages`` count is also kept for backward compat.
+
+    Args:
+        config: Meeting configuration dict.
+        num_parts: Number of transcript parts.
+        verification: Verification result dict (from :func:`verify_vtt_content`),
+            or ``None`` for dry-run.
+        chat_count: Number of extracted chat messages (backward compat).
+        participants: Optional :class:`MeetingParticipants` with
+            categorised participant lists.
+        chat_messages: Full list of :class:`ChatMessage` instances for the
+            ``"chat"`` array.  ``None`` when chat was not extracted.
+        include_transcript: Whether transcript component is included.
+        include_chat: Whether chat component is included.
+        include_metadata: Whether metadata component is included.
+
+    Returns:
+        Summary dict matching the JSON output schema.
+    """
+    summary: dict[str, object] = {"status": "ok"}
+    all_components = include_transcript and include_chat and include_metadata
+
+    # Meeting identity (always present)
+    summary["meeting"] = config["meeting"]
+
+    # Tenant (included only when --tenant was specified and verified)
+    if config.get("tenant"):
+        summary["tenant"] = config["tenant"]
+
+    time_text = config.get("meeting_time_text", "")
+    if time_text:
+        start_dt, end_dt = parse_meeting_times(time_text, config["date"])
+        summary["start"] = start_dt
+        if end_dt:
+            summary["end"] = end_dt
+    else:
+        summary["start"] = config["date"]
+        if config.get("time"):
+            summary["start"] = f"{config['date']}T{config['time']}"
+
+    # Participants (when metadata is included)
+    if include_metadata:
+        if participants is not None:
+            _add_participant_fields(summary, participants)
+        else:
+            _add_legacy_member_fields(summary, config)
+
+    # Transcript fields (when transcript is included)
+    if include_transcript:
+        summary["parts"] = num_parts
+
+        # Verification data (populated after download, absent for dry-run)
+        if verification and verification.get("valid"):
+            summary["cues"] = verification["cue_count"]
+            summary["speakers"] = verification["speakers"]
+            summary["file_size"] = verification["file_size"]
+        else:
+            # Dry-run: include speaker names with zero counts
+            speaker_map = config.get("speaker_map")
+            if speaker_map:
+                summary["speakers"] = dict.fromkeys(sorted(speaker_map.values()), 0)
+
+        # Structured transcript cues (when available)
+        if transcript_cues is not None:
+            summary["transcript"] = [_cue_to_dict(c) for c in transcript_cues]
+
+    # Chat (when chat is included)
+    if include_chat and chat_messages is not None:
+        summary["chat"] = [_chat_message_to_dict(m, config) for m in chat_messages]
+
+    # Backward compat: include chat_messages count when all components are on
+    if all_components and chat_count:
+        summary["chat_messages"] = chat_count
+    elif include_chat and not all_components and chat_count:
+        # Non-all-components mode: still include count for convenience
+        summary["chat_messages"] = chat_count
+
+    return summary
+
+
+def _chat_message_to_dict(message: ChatMessage, config: dict) -> dict:
+    """Convert a ChatMessage to a plain dict for JSON output.
+
+    Computes the offset from meeting start and includes reactions.
+    """
+    d: dict[str, object] = {
+        "author": message.author,
+        "text": message.text,
+    }
+
+    # Compute offset from meeting start
+    time_text = config.get("meeting_time_text", "")
+    offset = _compute_chat_offset(message.timestamp, time_text, config.get("date", ""))
+    d["offset"] = offset or None
+
+    # Reactions
+    if message.reactions:
+        d["reactions"] = [
+            {"type": r.type, "count": len(r.users), "users": r.users} for r in message.reactions
+        ]
+    else:
+        d["reactions"] = None
+
+    return d
+
+
+def _cue_to_dict(cue: TranscriptCue) -> dict:
+    """Convert a TranscriptCue to a plain dict for JSON output.
+
+    Returns:
+        Dict with keys: id, start, end, start_sec, end_sec, speaker, text.
+    """
+    return {
+        "id": cue.id,
+        "start": cue.start,
+        "end": cue.end,
+        "start_sec": cue.start_sec,
+        "end_sec": cue.end_sec,
+        "speaker": cue.speaker,
+        "text": cue.text,
+    }
+
+
+def _compute_chat_offset(timestamp: str, meeting_time_text: str, date: str) -> str:
+    """Compute HH:MM:SS.mmm offset from meeting start for a chat message.
+
+    Returns empty string if offset cannot be computed.
+    """
+    from datetime import datetime as dt
+
+    from teams_transcripts.domain.timestamps import format_vtt_timestamp
+
+    if not meeting_time_text:
+        return ""
+
+    start_dt_str, _ = parse_meeting_times(meeting_time_text, date)
+    if not start_dt_str:
+        return ""
+
+    try:
+        # Parse message timestamp and meeting start
+        msg_time = dt.fromisoformat(timestamp)
+        start_time = dt.fromisoformat(start_dt_str)
+        delta = msg_time - start_time
+        seconds = max(0.0, delta.total_seconds())
+        return format_vtt_timestamp(seconds)
+    except (ValueError, TypeError):
+        return ""
+
+
+def _member_to_dict(member: object) -> dict[str, str]:
+    """Convert a RosterMember to a plain dict with name, email, and optional rsvp_status."""
+    d: dict[str, str] = {"name": member.name, "email": member.email}  # type: ignore[union-attr]
+    rsvp = getattr(member, "rsvp_status", "")
+    if rsvp:
+        d["rsvp_status"] = rsvp
+    return d
+
+
+def _add_participant_fields(summary: dict, participants: MeetingParticipants) -> None:
+    """Add categorised participant fields to the summary dict."""
+    if participants.organiser:
+        org = participants.organiser[0]
+        summary["organiser"] = _member_to_dict(org)
+
+    if participants.invited:
+        summary["invited"] = [_member_to_dict(m) for m in participants.invited]
+
+    if participants.speakers:
+        summary["speakers_list"] = [_member_to_dict(m) for m in participants.speakers]
+
+    if participants.attendees:
+        summary["attendees"] = [_member_to_dict(m) for m in participants.attendees]
+
+
+def _add_legacy_member_fields(summary: dict, config: dict) -> None:
+    """Add legacy members/organiser fields from roster or speaker_map."""
+    roster = config.get("roster_members", [])
+    if roster:
+        summary["members"] = sorted(m["name"] for m in roster)
+        organisers = sorted(m["name"] for m in roster if m["role"] == "organiser")
+        if organisers:
+            summary["organiser"] = organisers[0] if len(organisers) == 1 else organisers
+    else:
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            summary["members"] = sorted(speaker_map.values())
+
+
+def verify_vtt_content(content: str, *, require_cues: bool = False) -> dict:
+    """Verify VTT content and return a summary dict.
+
+    This is the pure version of ``verify_output()`` -- it operates on
+    content strings rather than file paths.
+
+    Args:
+        content: VTT file content string.
+
+    Returns:
+        Dict with ``"valid"`` bool and either error info or
+        ``"cue_count"``, ``"speakers"`` keys.
+    """
+    if not content.startswith("WEBVTT"):
+        return {"valid": False, "error": "missing WEBVTT header"}
+
+    # Count cues
+    cue_count = len(re.findall(r"\d{2}:\d{2}:\d{2}\.\d{3} --> \d{2}:\d{2}:\d{2}\.\d{3}", content))
+    if require_cues and cue_count == 0:
+        return {"valid": False, "error": "no transcript cues found"}
+
+    # Extract speakers
+    speaker_pattern = re.compile(r"^<v ([^>]+)>", re.MULTILINE)
+    speakers = speaker_pattern.findall(content)
+    speaker_counts = Counter(speakers)
+
+    return {
+        "valid": True,
+        "cue_count": cue_count,
+        "speakers": dict(speaker_counts),
+        "file_size": len(content.encode("utf-8")),
+    }

teams_transcripts/domain/timestamps.py

@@ -0,0 +1,350 @@
+"""Pure timestamp parsing, formatting, and manipulation functions.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.  They form the foundation for VTT generation and
+meeting time resolution.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+# ---------------------------------------------------------------------------
+# VTT timestamp parsing and formatting
+# ---------------------------------------------------------------------------
+
+
+def parse_vtt_timestamp(ts: str) -> float:
+    """Parse a VTT timestamp (``HH:MM:SS.mmm``) to seconds.
+
+    Args:
+        ts: Timestamp string in ``HH:MM:SS.mmm`` format.
+
+    Returns:
+        Time in seconds as a float.
+    """
+    parts = ts.split(":")
+    h = int(parts[0])
+    m = int(parts[1])
+    s_ms = parts[2].split(".")
+    s = int(s_ms[0])
+    ms = int(s_ms[1]) if len(s_ms) > 1 else 0
+    return h * 3600 + m * 60 + s + ms / 1000
+
+
+def format_vtt_timestamp(seconds: float) -> str:
+    """Format seconds as a VTT timestamp (``HH:MM:SS.mmm``).
+
+    Negative values are clamped to zero.  Sub-millisecond fractions are
+    truncated (not rounded) to match the original implementation.
+
+    Args:
+        seconds: Time in seconds.
+
+    Returns:
+        Formatted timestamp string.
+    """
+    seconds = max(0.0, seconds)
+    h = int(seconds) // 3600
+    m = (int(seconds) % 3600) // 60
+    s = int(seconds) % 60
+    ms = int((seconds % 1) * 1000)
+    return f"{h:02d}:{m:02d}:{s:02d}.{ms:03d}"
+
+
+# ---------------------------------------------------------------------------
+# Approach-specific timestamp conversions
+# ---------------------------------------------------------------------------
+
+
+def sec_to_vtt_float(s: float) -> str:
+    """Convert float seconds to VTT timestamp (Approach A).
+
+    Identical to :func:`format_vtt_timestamp` -- this alias exists to
+    make the Approach A origin explicit.  Used when transcript data has
+    sub-second precision (React props extraction).
+
+    Args:
+        s: Time in seconds (float, may have fractional milliseconds).
+
+    Returns:
+        Formatted VTT timestamp.
+    """
+    s = max(0.0, s)
+    h = int(s) // 3600
+    m = (int(s) % 3600) // 60
+    sec = int(s) % 60
+    ms = int((s % 1) * 1000)
+    return f"{h:02d}:{m:02d}:{sec:02d}.{ms:03d}"
+
+
+def sec_to_vtt_int(s: int) -> str:
+    """Convert integer seconds to VTT timestamp (Approach B).
+
+    Always produces ``.000`` milliseconds since DOM-extracted timestamps
+    have only second-level granularity.
+
+    Args:
+        s: Time in integer seconds.
+
+    Returns:
+        Formatted VTT timestamp with ``.000`` milliseconds.
+    """
+    return f"{s // 3600:02d}:{(s % 3600) // 60:02d}:{s % 60:02d}.000"
+
+
+def ts_to_sec(ts: str | None) -> int | None:
+    """Convert a Teams DOM timestamp (``MM:SS`` or ``HH:MM:SS``) to seconds.
+
+    Used for Approach B (DOM extraction) where timestamps come from the
+    virtualised transcript list.
+
+    Args:
+        ts: Timestamp string, or ``None``/empty string.
+
+    Returns:
+        Integer seconds, or ``None`` when input is falsy.  Returns 0
+        for unrecognised formats.
+    """
+    if not ts:
+        return None
+    parts = ts.split(":")
+    if len(parts) == 2:
+        return int(parts[0]) * 60 + int(parts[1])
+    if len(parts) == 3:
+        return int(parts[0]) * 3600 + int(parts[1]) * 60 + int(parts[2])
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Occurrence duration parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_occurrence_duration(text: str) -> int | None:
+    """Parse meeting duration in seconds from occurrence dropdown text.
+
+    Expected format: ``'17 April 2026 19:30 -  20:00'`` or similar.
+
+    Handles midnight crossing (e.g. ``23:30 - 00:30`` = 60 minutes).
+
+    Args:
+        text: Raw occurrence text from the dropdown.
+
+    Returns:
+        Duration in seconds, or ``None`` if the text cannot be parsed.
+    """
+    m = re.search(r"(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})", text)
+    if not m:
+        return None
+    start_min = int(m.group(1)) * 60 + int(m.group(2))
+    end_min = int(m.group(3)) * 60 + int(m.group(4))
+    if end_min <= start_min:
+        end_min += 24 * 60  # crosses midnight
+    return (end_min - start_min) * 60
+
+
+# ---------------------------------------------------------------------------
+# Meeting time parsing
+# ---------------------------------------------------------------------------
+
+
+# Month name lookup for Recap header text.
+_MONTH_NAMES: dict[str, str] = {
+    "january": "01",
+    "february": "02",
+    "march": "03",
+    "april": "04",
+    "may": "05",
+    "june": "06",
+    "july": "07",
+    "august": "08",
+    "september": "09",
+    "october": "10",
+    "november": "11",
+    "december": "12",
+}
+
+
+def parse_meeting_times(text: str, fallback_date: str) -> tuple[str, str]:
+    """Parse occurrence text into ISO 8601 start and end datetime strings.
+
+    *text* has the form ``22 April 2026 11:15 -  12:00``.
+    *fallback_date* is ``YYYY-MM-DD`` used when the text cannot be parsed.
+
+    The Recap header displays times in the user's local timezone.  The
+    local UTC offset for the parsed date is appended so the output is a
+    fully-qualified ISO 8601 datetime (e.g. ``2026-04-22T11:15+01:00``).
+
+    Args:
+        text: Raw Recap header time text.
+        fallback_date: Date string to return when parsing fails.
+
+    Returns:
+        ``(start, end)`` where each is ``YYYY-MM-DDTHH:MM+HH:MM`` or
+        just ``YYYY-MM-DD`` if the time component is missing.
+    """
+    m = re.match(
+        r"(\d{1,2})\s+(\w+)\s+(\d{4})\s+(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2})",
+        text.strip(),
+    )
+    if not m:
+        return fallback_date, fallback_date
+
+    day = int(m.group(1))
+    month = _MONTH_NAMES.get(m.group(2).lower(), "01")
+    year = m.group(3)
+    start_time = m.group(4).zfill(5)  # ensure HH:MM
+    end_time = m.group(5).zfill(5)
+
+    date_str = f"{year}-{month}-{day:02d}"
+
+    # Determine the local UTC offset for this specific date.  The offset
+    # may differ from today's offset due to DST transitions.
+    sh, sm = (int(x) for x in start_time.split(":"))
+    try:
+        naive = datetime(int(year), int(month), day, sh, sm, tzinfo=timezone.utc)
+        local_dt = naive.astimezone(tz=None)
+        utc_offset = local_dt.utcoffset() or timedelta(0)
+    except (ValueError, OSError):
+        utc_offset = datetime.now(timezone.utc).astimezone().utcoffset() or timedelta(0)
+
+    offset_str = _format_utc_offset(utc_offset)
+
+    return f"{date_str}T{start_time}{offset_str}", f"{date_str}T{end_time}{offset_str}"
+
+
+# ---------------------------------------------------------------------------
+# UTC to local time conversion
+# ---------------------------------------------------------------------------
+
+
+def utc_to_local_iso(utc_timestamp: str) -> str:
+    """Convert a UTC ISO 8601 timestamp to local time with UTC offset.
+
+    Accepts strings like ``2026-04-22T10:15:48.462Z`` and returns
+    ``2026-04-22T11:15:48.462+01:00`` (for BST).  If parsing fails
+    the original string is returned unchanged.
+
+    Args:
+        utc_timestamp: UTC timestamp string (``Z`` or ``+00:00`` suffix).
+
+    Returns:
+        Local ISO 8601 string with UTC offset, or the original string
+        on parse failure.
+    """
+    try:
+        dt = datetime.fromisoformat(utc_timestamp.replace("Z", "+00:00"))
+        local_dt = dt.astimezone(tz=None)
+        offset = local_dt.utcoffset() or timedelta(0)
+        offset_str = _format_utc_offset(offset)
+        # Format with milliseconds if present in original
+        if "." in utc_timestamp:
+            ms = f"{local_dt.microsecond // 1000:03d}"
+            return f"{local_dt.strftime('%Y-%m-%dT%H:%M:%S')}.{ms}{offset_str}"
+        return local_dt.strftime(f"%Y-%m-%dT%H:%M:%S{offset_str}")
+    except (ValueError, OSError):
+        return utc_timestamp
+
+
+# ---------------------------------------------------------------------------
+# Timestamp fill algorithms (Approach B)
+# ---------------------------------------------------------------------------
+
+
+def forward_fill(segments: list[dict]) -> None:
+    """Forward-fill null timestamps: set each to ``last_good + 10``.
+
+    Modifies *segments* in place.  Leading ``None`` values are left
+    unchanged (handled by :func:`backfill`).
+
+    Args:
+        segments: List of segment dicts with a ``"ts_sec"`` key.
+    """
+    last_good = None
+    for seg in segments:
+        if seg["ts_sec"] is not None:
+            last_good = seg["ts_sec"]
+        elif last_good is not None:
+            seg["ts_sec"] = last_good + 10
+            last_good = seg["ts_sec"]
+
+
+def backfill(segments: list[dict]) -> None:
+    """Backfill remaining null timestamps: set each to ``next_good - 10``.
+
+    Values are clamped to 0.  Trailing ``None`` values are left unchanged
+    (handled by :func:`final_fallback`).  Modifies *segments* in place.
+
+    Args:
+        segments: List of segment dicts with a ``"ts_sec"`` key.
+    """
+    next_good = None
+    for seg in reversed(segments):
+        if seg["ts_sec"] is not None:
+            next_good = seg["ts_sec"]
+        elif next_good is not None:
+            seg["ts_sec"] = max(0, next_good - 10)
+            next_good = seg["ts_sec"]
+
+
+def final_fallback(segments: list[dict]) -> None:
+    """Set any remaining null timestamps to 0.
+
+    Called after :func:`forward_fill` and :func:`backfill` to handle the
+    edge case where all timestamps were ``None``.  Modifies *segments*
+    in place.
+
+    Args:
+        segments: List of segment dicts with a ``"ts_sec"`` key.
+    """
+    for seg in segments:
+        if seg["ts_sec"] is None:
+            seg["ts_sec"] = 0
+
+
+def detect_discontinuity(segments: list[dict]) -> list[dict]:
+    """Truncate segments at a timestamp discontinuity.
+
+    A discontinuity is defined as a gap > 600 seconds AND a timestamp
+    > 2x the running maximum.  These typically arise from virtualised
+    scroll artefacts in the Teams DOM.
+
+    With 2 or fewer segments, no truncation is applied.
+
+    Args:
+        segments: List of segment dicts with a ``"ts_sec"`` key.
+
+    Returns:
+        The (possibly truncated) segment list.
+    """
+    if len(segments) <= 2:
+        return segments
+    running_max = 0
+    cut_at = None
+    for i, seg in enumerate(segments):
+        ts = seg["ts_sec"]
+        if i > 0 and ts is not None and running_max > 0:
+            gap = ts - running_max
+            if gap > 600 and ts > running_max * 2:
+                cut_at = i
+                break
+        if ts is not None and ts > running_max:
+            running_max = ts
+    if cut_at is not None:
+        return segments[:cut_at]
+    return segments
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _format_utc_offset(utc_offset: timedelta) -> str:
+    """Format a UTC offset timedelta as ``+HH:MM`` or ``-HH:MM``."""
+    total_seconds = int(utc_offset.total_seconds())
+    sign = "+" if total_seconds >= 0 else "-"
+    abs_seconds = abs(total_seconds)
+    return f"{sign}{abs_seconds // 3600:02d}:{(abs_seconds % 3600) // 60:02d}"