meetings.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250
  1. """Graph-backed Teams meeting helpers for the plugin runtime."""
  2. from __future__ import annotations
  3. import base64
  4. import binascii
  5. import re
  6. import tempfile
  7. from functools import partial
  8. from pathlib import Path
  9. from typing import Any, Awaitable
  10. from urllib.parse import quote, unquote
  11. from plugins.teams_pipeline.models import MeetingArtifact, TeamsMeetingRef
  12. from tools.microsoft_graph_client import MicrosoftGraphAPIError, MicrosoftGraphClient
  13. # Graph uses both slash keys (users/{id}/...) and quoted keys (users('{id}')/...),
  14. # so every segment pattern has a quoted group and a slash group.
  15. _USERS_MEETING_RE = re.compile(r"(?i)(?:^|/)users(?:\('([^']+)'\)|/([^/'()]+))/onlineMeetings(?:\('([^']+)'\)|/([^/'?]+))")
  16. _COMM_MEETING_RE = re.compile(r"(?i)(?:^|/)communications/onlineMeetings(?:\('([^']+)'\)|/([^/'?]+))")
  17. _TRANSCRIPT_RE = re.compile(r"(?i)/transcripts(?:\('([^']+)'\)|/([^/'?]+))")
  18. _RECORDING_RE = re.compile(r"(?i)/recordings(?:\('([^']+)'\)|/([^/'?]+))")
  19. # Collection function names that the meeting regex can capture in place of a real meeting id.
  20. _RESOURCE_SENTINELS = frozenset({"getalltranscripts", "getallrecordings", "transcripts", "recordings"})
  21. class TeamsMeetingError(RuntimeError): """Base class for Teams meeting pipeline failures."""
  22. class TeamsMeetingNotFoundError(TeamsMeetingError): """Raised when the meeting cannot be resolved from Graph."""
  23. class TeamsMeetingArtifactNotFoundError(TeamsMeetingError): """Raised when a transcript or recording cannot be found."""
  24. class TeamsMeetingPermissionError(TeamsMeetingError): """Raised when Graph access is denied for the requested resource."""
  25. def _match_id(match: re.Match[str] | None, *groups: int) -> str | None:
  26. """Unquoted, stripped value of the first non-empty capture group, or None."""
  27. if match is None:
  28. return None
  29. return unquote(next((match.group(g) for g in groups if match.group(g)), "")).strip() or None
  30. def parse_graph_meeting_resource(resource: str) -> dict[str, str | None]:
  31. """Parse organizer, meeting, and artifact ids from a Graph resource or @odata.id."""
  32. text = str(resource or "").strip()
  33. users_match = _USERS_MEETING_RE.search(text)
  34. meeting_id = _match_id(users_match, 3, 4) or _match_id(_COMM_MEETING_RE.search(text), 1, 2)
  35. if meeting_id and meeting_id.lower() in _RESOURCE_SENTINELS:
  36. meeting_id = None
  37. return {
  38. "organizer_user_id": _match_id(users_match, 1, 2),
  39. "meeting_id": meeting_id,
  40. "transcript_id": _match_id(_TRANSCRIPT_RE.search(text), 1, 2),
  41. "recording_id": _match_id(_RECORDING_RE.search(text), 1, 2)}
  42. def looks_like_transcript_id(value: str, *, odata_type: str | None = None) -> bool:
  43. """True when a Graph id is a callTranscript artifact rather than an onlineMeeting."""
  44. if "calltranscript" in str(odata_type or "").lower():
  45. return True
  46. return "transcript" in str(value or "").lower() or "transcript" in _decoded_id_hint(str(value or ""))
  47. def _decoded_id_hint(value: str) -> str:
  48. """Best-effort base64 decode of a Graph id: getAllTranscripts ``resourceData.id`` blobs only carry
  49. their ``-TranscriptV2`` marker in the *decoded* payload. Lowercase decoded text, or "" if undecodable."""
  50. stripped = value.strip()
  51. if len(stripped) < 16:
  52. return ""
  53. padded = stripped + "=" * (-len(stripped) % 4)
  54. for decoder in (base64.urlsafe_b64decode, base64.b64decode):
  55. try:
  56. return decoder(padded).decode("utf-8", "ignore").lower()
  57. except (binascii.Error, ValueError):
  58. continue
  59. return ""
  60. def _meetings_collection(organizer_user_id: str | None) -> str:
  61. """Organizer-scoped collection when the organizer is known (required for app-only Graph access)."""
  62. return f"/users/{quote(organizer_user_id, safe='')}/onlineMeetings" if organizer_user_id else "/communications/onlineMeetings"
  63. def _meeting_path(meeting_ref: TeamsMeetingRef) -> str:
  64. return f"{_meetings_collection(meeting_ref.organizer_user_id)}/{quote(meeting_ref.meeting_id, safe='')}"
  65. def _wrap_graph_error(exc: MicrosoftGraphAPIError, *, missing_message: str) -> TeamsMeetingError:
  66. if exc.status_code in {401, 403}:
  67. return TeamsMeetingPermissionError(str(exc))
  68. return TeamsMeetingNotFoundError(missing_message) if exc.status_code == 404 else TeamsMeetingError(str(exc))
  69. async def _graph(awaitable: Awaitable[Any], *, missing_message: str) -> Any:
  70. """Await a Graph client call, translating MicrosoftGraphAPIError into TeamsMeetingError subclasses."""
  71. try:
  72. return await awaitable
  73. except MicrosoftGraphAPIError as exc:
  74. raise _wrap_graph_error(exc, missing_message=missing_message) from exc
  75. def _parse_organizer_user_id(payload: dict[str, Any]) -> str | None:
  76. organizer = payload.get("organizer")
  77. identity = organizer.get("identity") if isinstance(organizer, dict) else None
  78. user = identity.get("user") if isinstance(identity, dict) else None
  79. return user.get("id") if isinstance(user, dict) else None
  80. def _normalize_meeting_ref(payload: dict[str, Any], *, tenant_id: str | None = None, organizer_user_id: str | None = None) -> TeamsMeetingRef:
  81. metadata = {key: payload.get(key) for key in ("subject", "startDateTime", "endDateTime", "createdDateTime", "participants")
  82. if payload.get(key) is not None}
  83. chat = payload.get("chatInfo")
  84. thread_id = str(chat["threadId"]) if isinstance(chat, dict) and chat.get("threadId") else payload.get("threadId")
  85. return TeamsMeetingRef(
  86. meeting_id=str(payload.get("id") or "").strip(),
  87. organizer_user_id=organizer_user_id or _parse_organizer_user_id(payload),
  88. join_web_url=payload.get("joinWebUrl"), calendar_event_id=payload.get("calendarEventId"),
  89. thread_id=thread_id, tenant_id=tenant_id or payload.get("tenantId"), metadata=metadata)
  90. def _normalize_artifact(artifact_type: str, payload: dict[str, Any]) -> MeetingArtifact:
  91. return MeetingArtifact(
  92. artifact_type=artifact_type, # type: ignore[arg-type]
  93. artifact_id=str(payload.get("id") or "").strip(),
  94. display_name=payload.get("displayName") or payload.get("name"),
  95. content_type=payload.get("contentType") or payload.get("fileMimeType"),
  96. source_url=payload.get("webUrl") or payload.get("contentUrl"),
  97. download_url=(payload.get("@microsoft.graph.downloadUrl") or payload.get("downloadUrl")
  98. or payload.get("recordingContentUrl") or payload.get("transcriptContentUrl")),
  99. created_at=payload.get("createdDateTime"),
  100. available_at=payload.get("lastModifiedDateTime") or payload.get("meetingEndDateTime"),
  101. size_bytes=payload.get("size"), metadata=dict(payload))
  102. def _transcript_sort_key(artifact: MeetingArtifact) -> tuple[int, int, str]:
  103. """Prefer completed, downloadable, most recent transcripts (in that priority order)."""
  104. status = str(artifact.metadata.get("status") or "").lower()
  105. has_download = int(bool(artifact.download_url or artifact.source_url))
  106. is_completed = int(status in {"available", "completed", "succeeded"})
  107. stamp = artifact.available_at or artifact.created_at
  108. return (is_completed, has_download, stamp.isoformat() if stamp is not None else "")
  109. async def resolve_meeting_reference(
  110. client: MicrosoftGraphClient, *, meeting_id: str | None = None, join_web_url: str | None = None,
  111. tenant_id: str | None = None, organizer_user_id: str | None = None) -> TeamsMeetingRef:
  112. if meeting_id and looks_like_transcript_id(meeting_id):
  113. if not join_web_url:
  114. raise TeamsMeetingError("Refusing to GET /communications/onlineMeetings/{id} with a transcript id. "
  115. "Graph v1.0 does not support that id format; use the organizer-scoped meeting "
  116. "id from the notification @odata.id, or a join URL.")
  117. meeting_id = None
  118. collection = _meetings_collection(organizer_user_id)
  119. if meeting_id:
  120. missing = f"Teams meeting not found: {meeting_id}"
  121. path = f"{collection}/{quote(meeting_id, safe='')}"
  122. payload = await _graph(client.get_json(path), missing_message=missing)
  123. if not isinstance(payload, dict) or not payload.get("id"):
  124. raise TeamsMeetingNotFoundError(missing)
  125. elif join_web_url:
  126. missing = f"Teams meeting not found for join URL: {join_web_url}"
  127. params = {"$filter": f"JoinWebUrl eq '{join_web_url.replace(chr(39), chr(39) * 2)}'"}
  128. listing = await _graph(client.get_json(collection, params=params), missing_message=missing)
  129. candidates = listing.get("value") if isinstance(listing, dict) else None
  130. if not isinstance(candidates, list) or not candidates:
  131. raise TeamsMeetingNotFoundError(missing)
  132. payload = candidates[0]
  133. else:
  134. raise ValueError("Either meeting_id or join_web_url is required.")
  135. return _normalize_meeting_ref(payload, tenant_id=tenant_id, organizer_user_id=organizer_user_id)
  136. async def _list_artifacts(client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef, *, artifact_type: str) -> list[MeetingArtifact]:
  137. collection = f"{artifact_type}s"
  138. payloads = await _graph(
  139. client.collect_paginated(f"{_meeting_path(meeting_ref)}/{collection}"),
  140. missing_message=f"No {collection} found for Teams meeting {meeting_ref.meeting_id}")
  141. return [_normalize_artifact(artifact_type, payload) for payload in payloads if isinstance(payload, dict)]
  142. list_transcript_artifacts = partial(_list_artifacts, artifact_type="transcript")
  143. list_recording_artifacts = partial(_list_artifacts, artifact_type="recording")
  144. async def _download_artifact(
  145. client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef, artifact: MeetingArtifact, destination: Path, *,
  146. kind: str, **download_kwargs: Any) -> dict[str, Any]:
  147. path = artifact.download_url or f"{_meeting_path(meeting_ref)}/{kind}s/{quote(artifact.artifact_id, safe='')}/content"
  148. return await _graph(
  149. client.download_to_file(path, destination, **download_kwargs),
  150. missing_message=f"{kind.capitalize()} {artifact.artifact_id} not found for meeting {meeting_ref.meeting_id}")
  151. def select_preferred_transcript(candidates: list[MeetingArtifact]) -> MeetingArtifact | None:
  152. transcripts = [candidate for candidate in candidates if candidate.artifact_type == "transcript"]
  153. return max(transcripts, key=_transcript_sort_key) if transcripts else None
  154. async def download_transcript_text(
  155. client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef, transcript: MeetingArtifact, *, encoding: str = "utf-8") -> str:
  156. suffix = Path(transcript.display_name or "transcript.vtt").suffix or ".txt"
  157. with tempfile.TemporaryDirectory(prefix="teams-transcript-", ignore_cleanup_errors=True) as tmp_dir:
  158. destination = Path(tmp_dir) / f"transcript{suffix}"
  159. # Graph's transcript /content endpoint rejects JSON content negotiation.
  160. await _download_artifact(client, meeting_ref, transcript, destination, kind="transcript", headers={"Accept": "text/vtt"})
  161. text = destination.read_text(encoding=encoding).strip()
  162. if not text:
  163. raise TeamsMeetingArtifactNotFoundError(f"Transcript {transcript.artifact_id} for meeting {meeting_ref.meeting_id} was empty.")
  164. return text
  165. async def fetch_preferred_transcript_text(client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef) -> tuple[MeetingArtifact | None, str | None]:
  166. transcript = select_preferred_transcript(await list_transcript_artifacts(client, meeting_ref))
  167. if transcript is None:
  168. return None, None
  169. try:
  170. return transcript, await download_transcript_text(client, meeting_ref, transcript)
  171. except TeamsMeetingArtifactNotFoundError:
  172. return None, None
  173. async def download_recording_artifact(
  174. client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef, recording: MeetingArtifact, destination: str | Path) -> dict[str, Any]:
  175. destination_path = Path(destination)
  176. result = await _download_artifact(client, meeting_ref, recording, destination_path, kind="recording")
  177. return {
  178. "artifact": recording.to_dict(), "path": str(destination_path),
  179. "size_bytes": result.get("size_bytes") or recording.size_bytes,
  180. "content_type": result.get("content_type") or recording.content_type}
  181. async def enrich_meeting_with_call_record(
  182. client: MicrosoftGraphClient, meeting_ref: TeamsMeetingRef, *, call_record_id: str | None = None, allow_permission_errors: bool = True
  183. ) -> MeetingArtifact | None:
  184. """Call records need the extra CallRecords.Read.All scope, so denial is optional-soft (None)."""
  185. if not (call_record_id := str(call_record_id or meeting_ref.metadata.get("call_record_id") or "")):
  186. return None
  187. try:
  188. payload = await client.get_json(f"/communications/callRecords/{quote(call_record_id, safe='')}")
  189. except MicrosoftGraphAPIError as exc:
  190. if exc.status_code == 404 or (exc.status_code in {401, 403} and allow_permission_errors):
  191. return None
  192. raise _wrap_graph_error(exc, missing_message=f"Call record not found: {call_record_id}") from exc
  193. if not isinstance(payload, dict) or not payload.get("id"):
  194. return None
  195. metrics = {"version": payload.get("version"), "modalities": payload.get("modalities"),
  196. "participant_count": len(payload.get("participants") or []), "organizer": _parse_organizer_user_id(payload)}
  197. if sessions := payload.get("sessions"):
  198. metrics["session_count"] = len(sessions)
  199. return MeetingArtifact(
  200. artifact_type="call_record", artifact_id=str(payload["id"]), display_name=payload.get("type") or "call_record",
  201. source_url=payload.get("webUrl"), created_at=payload.get("startDateTime"), available_at=payload.get("endDateTime"),
  202. metadata={"call_record": payload, "metrics": metrics})