teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/domain/models.py

@@ -0,0 +1,531 @@
+"""Domain models -- immutable data classes for the transcript pipeline.
+
+All models are plain data holders with no I/O, no network access, and no
+dependency on infrastructure or adapters.  They form the shared vocabulary
+across the hexagonal architecture.
+
+Schema version: 2.2.0
+Created: 2026-04-25
+Last updated: 2026-05-01  -- added DownloadInput Pydantic validation model
+"""
+
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass, field
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+if typing.TYPE_CHECKING:
+    import datetime as dt
+
+# ---------------------------------------------------------------------------
+# Transcript domain objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TranscriptCue:
+    """A structured transcript cue for JSON output.
+
+    Represents a single cue parsed from VTT content, with both formatted
+    timestamp strings and numeric seconds for programmatic consumption.
+
+    Fields:
+        id: Sequential cue identifier (1-based).
+        start: Start timestamp as VTT string (``HH:MM:SS.mmm``).
+        end: End timestamp as VTT string (``HH:MM:SS.mmm``).
+        start_sec: Start time in seconds (float).
+        end_sec: End time in seconds (float).
+        speaker: Speaker display name, or ``None`` when no ``<v>`` tag
+            is present on the cue.
+        text: Plain text content (voice tags stripped).
+    """
+
+    id: int
+    start: str
+    end: str
+    start_sec: float
+    end_sec: float
+    speaker: str | None
+    text: str
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A single transcript segment (cue) extracted from the Teams DOM.
+
+    Represents one speaker turn with timing information.  Used as the
+    intermediate representation between DOM extraction and VTT generation.
+
+    Fields:
+        speaker: Display name of the speaker (may contain HTML entities
+            in raw form; cleaned before VTT output).
+        text: Spoken text content (may contain HTML in raw form).
+        start_sec: Start time in seconds from meeting start.  May be
+            ``None`` when the DOM element lacks timing data (forward-fill
+            is applied later).
+        end_sec: End time in seconds from meeting start.  May be ``None``
+            (back-fill or default offset is applied later).
+    """
+
+    speaker: str
+    text: str
+    start_sec: float | None = None
+    end_sec: float | None = None
+
+
+@dataclass(frozen=True)
+class RosterMember:
+    """A member from the meeting roster popover.
+
+    Fields:
+        name: Display name (cleaned of suffixes like "(Guest)").
+        email: Email address.  Empty string when unavailable.
+        object_id: Azure AD object ID (GUID).  Empty string when unavailable.
+        role: Either ``"organiser"`` or ``"member"``.
+        rsvp_status: Calendar response status.  One of ``"accepted"``,
+            ``"tentative"``, ``"declined"``, ``"none"`` (no response),
+            or ``""`` (unknown / not available).
+    """
+
+    name: str
+    email: str = ""
+    object_id: str = ""
+    role: str = "member"
+    rsvp_status: str = ""
+
+
+@dataclass(frozen=True)
+class MeetingParticipants:
+    """Categorised meeting participant lists.
+
+    Combines data from multiple extraction sources (participant popover,
+    Recap Speakers tab, Event/Call ``<partlist>`` XML) into four
+    disjoint-ish categories:
+
+    - **organiser**: the meeting creator (usually 1, rarely 0).
+    - **invited**: everyone on the meeting chat thread (full membership).
+    - **speakers**: those who spoke during the meeting (from Recap).
+    - **attendees**: those who joined the call (from the Event/Call
+      partlist -- may be incomplete due to Teams truncation).
+
+    Note: ``speakers`` and ``attendees`` are subsets of ``invited``.
+    A person may appear in both ``speakers`` and ``attendees``.
+
+    Fields:
+        organiser: The meeting organiser(s).  Usually a single-element
+            list; empty when the organiser cannot be identified.
+        invited: All members of the meeting chat thread, sorted by name.
+        speakers: Members who spoke, sorted by name.
+        attendees: Members who joined the call, sorted by name.
+
+    Schema version: 1.1.0
+    """
+
+    organiser: list[RosterMember] = field(default_factory=list)
+    invited: list[RosterMember] = field(default_factory=list)
+    speakers: list[RosterMember] = field(default_factory=list)
+    attendees: list[RosterMember] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Reaction:
+    """A reaction on a chat message.
+
+    Fields:
+        type: Emotion key (e.g. ``"like"``, ``"heart"``).
+        users: List of resolved display names.  May be empty when
+            only a summary count is available.
+    """
+
+    type: str
+    users: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ChatMessage:
+    """A chat message extracted from the meeting thread.
+
+    Fields:
+        timestamp: Local ISO 8601 datetime with timezone offset
+            (e.g. ``"2026-04-22T11:15:48+01:00"``).
+        author: Resolved display name of the message author.
+        text: Plain-text content (HTML stripped).
+        reactions: List of reactions, or ``None`` when no reactions exist.
+    """
+
+    timestamp: str
+    author: str
+    text: str
+    reactions: list[Reaction] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Verification result
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """Result of verifying a VTT file's content.
+
+    Fields:
+        valid: Whether the content passed all checks.
+        cue_count: Number of cues found (0 when invalid).
+        speakers: Mapping of speaker name to cue count.  Empty when invalid.
+        error: Human-readable error description.  Empty string when valid.
+    """
+
+    valid: bool
+    cue_count: int = 0
+    speakers: dict[str, int] = field(default_factory=dict)
+    error: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Result summary
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ResultSummary:
+    """Structured result summary for JSON output and dry-run display.
+
+    Mutable because fields are populated incrementally during the
+    pipeline (metadata first, then verification data, then chat count).
+
+    Fields:
+        status: Always ``"ok"`` for successful runs.
+        meeting: Meeting name as provided by the user.
+        tenant: Tenant domain name (e.g. ``"abccorp.com"``), or ``None``
+            when ``--tenant`` was not specified.  Included in JSON output
+            only when not ``None``.
+        start: ISO datetime or date string for the meeting start.
+        end: ISO datetime string for the meeting end, or ``None``.
+        members: Sorted list of member display names, or ``None``.
+        organiser: Single organiser name, list of names, or ``None``.
+        parts: Number of transcript parts detected.
+        cues: Total cue count from verification, or ``None`` before download.
+        speakers: Mapping of speaker name to cue count, or ``None``.
+        file_size: Output file size in bytes, or ``None`` before download.
+        chat_messages: Count of extracted chat messages, or ``None``.
+        dry_run: ``True`` only for dry-run output.
+        file: Output file path (when writing to file), or ``None``.
+        transcript: Structured cue list for JSON output, or ``None``.
+    """
+
+    status: str = "ok"
+    meeting: str = ""
+    tenant: str | None = None
+    start: str = ""
+    end: str | None = None
+    members: list[str] | None = None
+    organiser: str | list[str] | None = None
+    parts: int = 1
+    cues: int | None = None
+    speakers: dict[str, int] | None = None
+    file_size: int | None = None
+    chat_messages: int | None = None
+    dry_run: bool = False
+    file: str | None = None
+    transcript: list[dict] | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to a plain dict, omitting ``None`` values.
+
+        Matches the JSON output schema: keys with ``None`` values are
+        excluded, and ``dry_run`` is only included when ``True``.
+        """
+        d: dict[str, object] = {"status": self.status}
+        d["meeting"] = self.meeting
+        if self.tenant is not None:
+            d["tenant"] = self.tenant
+        d["start"] = self.start
+        if self.end is not None:
+            d["end"] = self.end
+        if self.members is not None:
+            d["members"] = self.members
+        if self.organiser is not None:
+            d["organiser"] = self.organiser
+        d["parts"] = self.parts
+        if self.cues is not None:
+            d["cues"] = self.cues
+        if self.speakers is not None:
+            d["speakers"] = self.speakers
+        if self.file_size is not None:
+            d["file_size"] = self.file_size
+        if self.chat_messages is not None:
+            d["chat_messages"] = self.chat_messages
+        if self.dry_run:
+            d["dry_run"] = True
+        if self.file is not None:
+            d["file"] = self.file
+        if self.transcript is not None:
+            d["transcript"] = self.transcript
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Meeting configuration
+# ---------------------------------------------------------------------------
+
+
+class MeetingConfig(BaseModel):
+    """Resolved meeting configuration from CLI args and environment.
+
+    Immutable once constructed by ``infrastructure.config.resolve_config()``.
+    Passed through the pipeline as the single source of configuration truth.
+
+    This is a frozen Pydantic model.  To create a modified copy (e.g. after
+    resolving ``--meeting-id`` via MCPS), use ``model_copy(update={...})``.
+
+    Fields:
+        meeting: Meeting name search string (``--meeting``).  Empty string
+            when ``--meeting-id`` is used instead.
+        meeting_id: Meeting UUID from ``--meeting-id``, or ``None`` when
+            ``--meeting`` is used instead.  When set, the pipeline resolves the
+            meeting subject via MCPS before searching, and verifies the
+            thread_id after navigation.
+        call_id: Call identifier from ``--call-id``, or ``None`` when not
+            specified.  When set, the pipeline searches MCPS for the exact
+            call_id match and resolves subject, date, and thread_id.  This
+            is the preferred identifier for recurring meetings as it uniquely
+            identifies a specific occurrence.
+        date: Target date as ``YYYY-MM-DD`` string.
+        time: Target time as ``HH:MM`` string, or ``None`` for date-only.
+        output: Output file path.  ``None`` during ``--dry-run``.
+        output_to_stdout: ``True`` when no ``--output`` was given (content
+            goes to stdout at the end).
+        dry_run: ``True`` for ``--dry-run`` mode.
+        port: CDP debugging port number.
+        gcp_project: Google Cloud project ID for Vertex AI.
+        gcp_region: Google Cloud region for Vertex AI.
+        model: LLM model identifier.
+        adc: Path to application default credentials JSON.
+        output_format: ``"vtt"`` or ``"json"``.
+        tenant: Tenant domain name for verification (e.g. ``"abccorp.com"``),
+            or ``None`` to skip tenant checking.
+        quiet: Suppress diagnostic output.
+        verbose: Enable verbose diagnostic output.
+        include_transcript: Include transcript cues in output.
+        include_chat: Include chat messages in output.
+        include_metadata: Include participant metadata in output.
+        force_restart: Allow Teams restart even when call state is active or unknown.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    meeting: str
+    date: str
+    time: str | None
+    output: str | None
+    output_to_stdout: bool
+    dry_run: bool
+    port: int
+    gcp_project: str
+    gcp_region: str
+    model: str
+    adc: str
+    output_format: str
+    meeting_id: str | None = None
+    call_id: str | None = None
+    tenant: str | None = None
+    quiet: bool = False
+    verbose: bool = False
+    include_transcript: bool = True
+    include_chat: bool = True
+    include_metadata: bool = True
+    force_restart: bool = False
+
+    @property
+    def format_json(self) -> bool:
+        """Whether output format is JSON."""
+        return self.output_format == "json"
+
+    @property
+    def all_components(self) -> bool:
+        """Whether all three output components are included."""
+        return self.include_transcript and self.include_chat and self.include_metadata
+
+
+# ---------------------------------------------------------------------------
+# Download input validation (Pydantic)
+# ---------------------------------------------------------------------------
+
+
+class DownloadInput(BaseModel):
+    """Validated download arguments shared by MCP tools and CLI config.
+
+    Captures the core argument-combination constraints that apply regardless
+    of entry point (MCP ``download()`` tool, CLI ``_resolve_config_inner()``).
+    All fields are optional with sensible defaults; the ``@model_validator``
+    enforces mutual-exclusivity and at-least-one rules.
+
+    Construct this early in both code paths.  ``ValidationError`` is then
+    either converted to ``exit_error()`` (CLI) or propagated to the MCP
+    framework (which returns a structured error to the agent).
+
+    Fields:
+        meeting: Meeting name search string.  Mutually exclusive with
+            ``meeting_id`` and ``call_id``.
+        meeting_id: Meeting UUID.  Mutually exclusive with ``meeting``,
+            ``call_id``, ``date``, and ``time``.
+        call_id: Call identifier (from list_transcripts output).  Mutually
+            exclusive with ``meeting``, ``meeting_id``, ``date``, and ``time``.
+            Uniquely identifies a specific occurrence of a recurring meeting.
+        date: Target date as ``YYYY-MM-DD``.  Incompatible with
+            ``meeting_id`` and ``call_id`` (date is resolved automatically).
+        time: Target time as ``HH:MM``.  Incompatible with ``meeting_id``
+            and ``call_id``.
+        include_transcript: Whether to download the transcript.
+        include_chat: Whether to download chat messages.
+        include_metadata: Whether to download participant metadata.
+
+    Schema version: 1.1.0
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    meeting: str | None = None
+    meeting_id: str | None = None
+    call_id: str | None = None
+    date: str | None = None
+    time: str | None = None
+    include_transcript: bool = True
+    include_chat: bool = True
+    include_metadata: bool = True
+    dry_run: bool = False
+
+    @model_validator(mode="after")
+    def _check_constraints(self) -> DownloadInput:
+        """Enforce argument-combination constraints.
+
+        Rules:
+            1. ``meeting_id``, ``call_id``, and ``meeting`` are mutually exclusive.
+            2. At least one of ``meeting_id``, ``call_id``, or ``meeting`` is required.
+            3. ``date`` is incompatible with ``meeting_id`` and ``call_id``.
+            4. ``time`` is incompatible with ``meeting_id`` and ``call_id``.
+            5. At least one content flag must be ``True``.
+            6. ``meeting_id`` must be a valid UUID.
+            7. ``call_id`` must be a non-empty string (no format constraint).
+        """
+        id_sources = sum(1 for x in (self.meeting_id, self.call_id, self.meeting) if x)
+        if id_sources > 1:
+            raise ValueError(
+                "meeting_id, call_id, and meeting are mutually exclusive. "
+                "Pass exactly one identifier."
+            )
+        if id_sources == 0:
+            raise ValueError("One of meeting_id, call_id, or meeting is required.")
+        if self.meeting_id and self.date:
+            raise ValueError(
+                "date is incompatible with meeting_id. "
+                "The meeting date is resolved automatically from the UUID."
+            )
+        if self.meeting_id and self.time:
+            raise ValueError(
+                "time is incompatible with meeting_id. "
+                "The meeting time is resolved automatically from the UUID."
+            )
+        if self.call_id and self.date:
+            raise ValueError(
+                "date is incompatible with call_id. "
+                "The meeting date is resolved automatically from the call ID."
+            )
+        if self.call_id and self.time:
+            raise ValueError(
+                "time is incompatible with call_id. "
+                "The meeting time is resolved automatically from the call ID."
+            )
+        if self.meeting_id:
+            try:
+                UUID(self.meeting_id)
+            except ValueError as exc:
+                raise ValueError("meeting_id must be a UUID.") from exc
+        if self.call_id is not None and not self.call_id.strip():
+            raise ValueError("call_id must be a non-empty string.")
+        if (
+            not self.include_transcript
+            and not self.include_chat
+            and not self.include_metadata
+            and not self.dry_run
+        ):
+            raise ValueError(
+                "At least one of include_transcript, include_chat, "
+                "or include_metadata must be True."
+            )
+        return self
+
+
+# ---------------------------------------------------------------------------
+# CDP target (lightweight typed wrapper)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CdpTarget:
+    """A Chrome DevTools Protocol page target.
+
+    Fields:
+        id: Target identifier string.
+        url: Page URL.
+        title: Page title.
+        ws_url: WebSocket debugger URL for connecting.
+    """
+
+    id: str
+    url: str = ""
+    title: str = ""
+    ws_url: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict) -> CdpTarget:
+        """Construct from a raw CDP ``/json`` response entry."""
+        return cls(
+            id=d.get("id", ""),
+            url=d.get("url", ""),
+            title=d.get("title", ""),
+            ws_url=d.get("webSocketDebuggerUrl", ""),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Meeting artifact (for --list-transcripts)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MeetingArtifact:
+    """A meeting with associated artifacts discovered via the MCPS API.
+
+    Represents a single meeting returned by
+    ``startListArtifactsByUserWorkflow``.  Each meeting may have a
+    transcript, a recording, or both.
+
+    Fields:
+        subject: Meeting subject line (may be empty for unnamed meetings).
+        thread_id: Teams thread identifier (``19:meeting_...``).
+        call_id: Call identifier from MCPS.
+        ical_uid: iCalendar UID for calendar correlation.
+        date: Date the meeting occurred.
+        has_transcript: Whether a TranscriptV2 resource is present.
+        has_recording: Whether a Recording resource is present.
+        transcript_url: SharePoint URL for transcript content download,
+            or ``None`` when no transcript is available.
+        recording_url: SharePoint URL for recording download,
+            or ``None`` when no recording is available.
+
+    Schema version: 1.0.0
+    """
+
+    subject: str
+    thread_id: str
+    call_id: str
+    ical_uid: str
+    date: dt.date
+    has_transcript: bool
+    has_recording: bool
+    transcript_url: str | None = None
+    recording_url: str | None = None