mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/graph/teams.py

@@ -0,0 +1,240 @@
+"""Graph operations for Teams and channels (spec §8.7).
+
+Pure: client and parameters in, Graph dicts, a `PageResult` or a `Plan` out.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+
+from mgraphctl import odata, resolve
+from mgraphctl.html import to_markdown
+from mgraphctl.http import (
+    JSON_HEADERS,
+    GraphClient,
+    PageResult,
+    Plan,
+    PlannedRequest,
+    filter_page,
+    with_routing,
+)
+from mgraphctl.render import Column, fmt_dt, parse_graph_dt, truncate
+
+CHANNEL_SELECT = "id,displayName,description,membershipType"
+# The Teams endpoints reject a `$top` above 50.
+PAGE_MEMBERS, CAP_MEMBERS = 50, 999
+PAGE_MESSAGES, CAP_MESSAGES = 50, 200
+CAP_TEAMS = CAP_CHANNELS = 999
+BODY_CAP = 300
+
+
+def list_teams(client: GraphClient) -> PageResult:
+    """Every team the signed-in user joined. `/me/joinedTeams` takes no OData parameters."""
+    return client.paginate("/me/joinedTeams", limit=None, all_=True, cap=CAP_TEAMS, page_size=None)
+
+
+def resolve_team(client: GraphClient, value: str) -> dict:
+    """A GUID (or `id:`-forced value) as-is, else the team of that display name (§6.6)."""
+    bare, _ = resolve.split_id_prefix(value)
+    if resolve.looks_like_id(value, "team"):
+        return {"id": bare}
+    return resolve.pick_unique(list_teams(client).items, "displayName", value, what="team")
+
+
+def resolve_channel(client: GraphClient, team_id: str, value: str) -> dict:
+    """A `19:` id (or `id:`-forced value) as-is, else the channel of that display name (§6.6)."""
+    bare, _ = resolve.split_id_prefix(value)
+    if resolve.looks_like_id(value, "channel"):
+        return {"id": bare}
+    channels = list_channels(client, team_id).items
+    return resolve.pick_unique(channels, "displayName", value, what="channel")
+
+
+def get_team(client: GraphClient, team_id: str) -> dict:
+    return client.get(odata.p("teams", team_id))
+
+
+def list_members(client: GraphClient, team_id: str, *, limit: int | None, all_: bool) -> PageResult:
+    return client.paginate(
+        odata.p("teams", team_id, "members"),
+        limit=limit,
+        all_=all_,
+        cap=CAP_MEMBERS,
+        page_size=PAGE_MEMBERS,
+    )
+
+
+def list_channels(client: GraphClient, team_id: str) -> PageResult:
+    return client.paginate(
+        odata.p("teams", team_id, "channels"),
+        params={"$select": CHANNEL_SELECT},
+        limit=None,
+        all_=True,
+        cap=CAP_CHANNELS,
+        page_size=None,
+    )
+
+
+def get_channel(client: GraphClient, team_id: str, channel_id: str) -> dict:
+    return client.get(odata.p("teams", team_id, "channels", channel_id))
+
+
+def _renderable(message: dict) -> bool:
+    """Tombstones and forward-compatible kinds carry no body worth showing (spec §8.7)."""
+    if message.get("deletedDateTime"):
+        return False
+    return message.get("messageType") != "unknownFutureValue"
+
+
+def _keep(page: PageResult) -> PageResult:
+    return filter_page(page, _renderable)
+
+
+def chain_modified(message: dict) -> datetime | None:
+    """When the message's whole reply chain was last touched, which is how Graph orders it.
+
+    Graph sorts channel messages "by the last modified date of the entire reply chain", so a
+    root message's own `lastModifiedDateTime` is not the key the feed is in order of. With
+    `--with-replies` the replies are in hand and the real key can be computed; without them
+    the root's own timestamp is the best available approximation.
+    """
+    stamps = [
+        parse_graph_dt(m.get("lastModifiedDateTime") or m.get("createdDateTime"))
+        for m in [message, *(message.get("replies") or [])]
+    ]
+    known = [s for s in stamps if s is not None]
+    return max(known) if known else None
+
+
+def _window_filter(
+    after: datetime | None, before: datetime | None
+) -> Callable[[dict], bool] | None:
+    """Keep the messages whose reply chain was last touched inside the window."""
+    if after is None and before is None:
+        return None
+
+    def keep(message: dict) -> bool:
+        stamp = chain_modified(message)
+        if stamp is None:  # undatable: keep it rather than silently drop a message
+            return True
+        if after is not None and stamp <= after:
+            return False
+        return before is None or stamp < before
+
+    return keep
+
+
+def _before_window(after: datetime | None) -> Callable[[dict], bool] | None:
+    """Page no further once a message's chain was last touched at or before `after`."""
+    if after is None:
+        return None
+
+    def past_it(message: dict) -> bool:
+        stamp = chain_modified(message)
+        return stamp is not None and stamp <= after
+
+    return past_it
+
+
+def channel_messages(
+    client: GraphClient,
+    team_id: str,
+    channel_id: str,
+    *,
+    with_replies: bool,
+    after: datetime | None = None,
+    before: datetime | None = None,
+    limit: int | None,
+    all_: bool,
+) -> PageResult:
+    """Channel messages, newest-modified first, optionally narrowed to a time window.
+
+    The window is applied here rather than as a `$filter`: Graph documents `$top` and
+    `$expand` as the only query parameters this endpoint supports (v1.0 and beta alike), so a
+    `$filter` would be rejected or — worse — ignored, and an ignored one would dress an
+    unfiltered page up as a window. Since the feed is ordered newest-first, paging can still
+    stop at the far edge of the window instead of walking to the cap.
+    """
+    params = {"$expand": "replies"} if with_replies else None
+    keep = _window_filter(after, before)
+    page = client.paginate(
+        odata.p("teams", team_id, "channels", channel_id, "messages"),
+        params=params,
+        limit=limit,
+        all_=all_,
+        cap=CAP_MESSAGES,
+        page_size=PAGE_MESSAGES,
+        stop=_before_window(after),
+    )
+    page = with_routing(_keep(page), teamId=team_id, channelId=channel_id)
+    return page if keep is None else filter_page(page, keep)
+
+
+def channel_replies(
+    client: GraphClient,
+    team_id: str,
+    channel_id: str,
+    msg_id: str,
+    *,
+    limit: int | None,
+    all_: bool,
+) -> PageResult:
+    page = client.paginate(
+        odata.p("teams", team_id, "channels", channel_id, "messages", msg_id, "replies"),
+        limit=limit,
+        all_=all_,
+        cap=CAP_MESSAGES,
+        page_size=PAGE_MESSAGES,
+    )
+    return with_routing(_keep(page), teamId=team_id, channelId=channel_id)
+
+
+def message_sender(message: dict) -> str:
+    """The display name behind a message's `from`, whichever identity kind carries it."""
+    identity = message.get("from") or {}
+    for kind in ("user", "application", "device"):
+        name = (identity.get(kind) or {}).get("displayName")
+        if name:
+            return name
+    return ""
+
+
+def render_message_body(m: dict, full: bool) -> str:
+    """One line of body text: HTML through Markdown, capped at 300 chars unless `full`."""
+    body = m.get("body") or {}
+    content = body.get("content") or ""
+    if (body.get("contentType") or "").lower() == "html":
+        content = to_markdown(content, mode="teams")
+    single_line = " ".join(content.split())
+    return single_line if full else truncate(single_line, BODY_CAP)
+
+
+def message_columns(tz: str, full: bool) -> list[Column]:
+    return [
+        Column("created", lambda m: fmt_dt(m.get("createdDateTime"), tz)),
+        Column("id", "id"),
+        Column("from", message_sender),
+        Column("body", lambda m: render_message_body(m, full)),
+    ]
+
+
+def plan_channel_send(
+    client: GraphClient,
+    team_id: str,
+    channel_id: str,
+    *,
+    body: str,
+    html: bool,
+    subject: str | None,
+    reply_to: str | None,
+) -> Plan:
+    """One POST. Plain text goes out as `contentType: "text"`, so nothing needs escaping."""
+    segments = ["teams", team_id, "channels", channel_id, "messages"]
+    if reply_to is not None:
+        segments += [reply_to, "replies"]
+    payload: dict[str, object] = {}
+    if subject is not None:
+        payload["subject"] = subject
+    payload["body"] = {"contentType": "html" if html else "text", "content": body}
+    return [PlannedRequest("POST", client.url(odata.p(*segments)), dict(JSON_HEADERS), payload)]

mgraphctl/graph/todo.py

@@ -0,0 +1,199 @@
+"""Graph operations for Microsoft To Do (spec §8.15).
+
+Pure: client and parameters in, Graph dicts / `PageResult` / `Plan` out.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from mgraphctl import odata, render
+from mgraphctl.errors import UsageError
+from mgraphctl.http import JSON_HEADERS, GraphClient, PageResult, Plan, PlannedRequest
+from mgraphctl.resolve import looks_like_id, pick_unique, split_id_prefix
+
+LIST_PAGE = 100
+TASK_PAGE = 100
+CAP_TASKS = 500
+MESSAGE_SELECT = "subject,webLink,bodyPreview,from,receivedDateTime"
+IMPORTANCE_VALUES = ("low", "normal", "high")
+STATUS_VALUES = ("notStarted", "inProgress", "completed", "waitingOnOthers", "deferred")
+WELLKNOWN_ALIASES = {"defaultlist": "defaultList", "flaggedemails": "flaggedEmails"}
+
+
+def _run(client: GraphClient, plan: Plan) -> Any:
+    """Execute every step of `plan` in order, returning the last step's result."""
+    result: Any = None
+    for step in plan:
+        result = client.execute(step)
+    return result
+
+
+# --------------------------------------------------------------------------- reads
+
+
+def list_lists(client: GraphClient) -> list[dict]:
+    payload = client.get("/me/todo/lists", params={"$top": LIST_PAGE}) or {}
+    return payload.get("value") or []
+
+
+def resolve_list(client: GraphClient, value: str) -> dict:
+    """A list id, well-known name (`defaultList`/`flaggedEmails`), or `displayName` (§6.6)."""
+    if looks_like_id(value, "todo_list"):
+        bare, _ = split_id_prefix(value)
+        return {"id": bare}
+    lists_ = list_lists(client)
+    wellknown = WELLKNOWN_ALIASES.get(value.strip().lower())
+    if wellknown is not None:
+        return pick_unique(lists_, "wellknownListName", wellknown, what="list")
+    return pick_unique(lists_, "displayName", value, what="list")
+
+
+def list_tasks(
+    client: GraphClient,
+    list_id: str,
+    *,
+    include_completed: bool = False,
+    limit: int | None,
+    all_: bool,
+) -> PageResult:
+    params: dict[str, object] = {}
+    if not include_completed:
+        params["$filter"] = "status ne 'completed'"
+    path = odata.p("me", "todo", "lists", list_id, "tasks")
+    return client.paginate(
+        path,
+        params=params,
+        outlook_tz=True,
+        limit=limit,
+        all_=all_,
+        cap=CAP_TASKS,
+        page_size=TASK_PAGE,
+    )
+
+
+def get_task(client: GraphClient, list_id: str, task_id: str) -> dict:
+    path = odata.p("me", "todo", "lists", list_id, "tasks", task_id)
+    return client.get(path, params={"$expand": "checklistItems,linkedResources"}, outlook_tz=True)
+
+
+# --------------------------------------------------------------------------- writes
+
+
+def task_body(
+    *,
+    title: str | None = None,
+    due: datetime | None = None,
+    body_text: str | None = None,
+    importance: str | None = None,
+    reminder: datetime | None = None,
+    start: datetime | None = None,
+    status: str | None = None,
+    tz: str,
+) -> dict:
+    body: dict[str, Any] = {}
+    if title is not None:
+        body["title"] = title
+    if body_text is not None:
+        body["body"] = {"content": body_text, "contentType": "text"}
+    if importance is not None:
+        if importance not in IMPORTANCE_VALUES:
+            raise UsageError("USAGE", "--importance must be low, normal or high")
+        body["importance"] = importance
+    if due is not None:
+        body["dueDateTime"] = render.to_graph_dtz(due, tz)
+    if reminder is not None:
+        body["reminderDateTime"] = render.to_graph_dtz(reminder, tz)
+        body["isReminderOn"] = True
+    if start is not None:
+        body["startDateTime"] = render.to_graph_dtz(start, tz)
+    if status is not None:
+        if status not in STATUS_VALUES:
+            raise UsageError("USAGE", f"--status must be one of {', '.join(STATUS_VALUES)}")
+        body["status"] = status
+    return body
+
+
+def plan_create(client: GraphClient, list_id: str, **opts: Any) -> Plan:
+    body = task_body(**opts)
+    url = client.url(odata.p("me", "todo", "lists", list_id, "tasks"))
+    return [PlannedRequest("POST", url, dict(JSON_HEADERS), body)]
+
+
+def run_create(client: GraphClient, list_id: str, **opts: Any) -> dict:
+    return _run(client, plan_create(client, list_id, **opts))
+
+
+def plan_update(client: GraphClient, list_id: str, task_id: str, **opts: Any) -> Plan:
+    body = task_body(**opts)
+    url = client.url(odata.p("me", "todo", "lists", list_id, "tasks", task_id))
+    return [PlannedRequest("PATCH", url, dict(JSON_HEADERS), body)]
+
+
+def run_update(client: GraphClient, list_id: str, task_id: str, **opts: Any) -> dict:
+    return _run(client, plan_update(client, list_id, task_id, **opts))
+
+
+def plan_complete(client: GraphClient, list_id: str, task_id: str, *, tz: str) -> Plan:
+    return plan_update(client, list_id, task_id, status="completed", tz=tz)
+
+
+def run_complete(client: GraphClient, list_id: str, task_id: str, *, tz: str) -> dict:
+    return _run(client, plan_complete(client, list_id, task_id, tz=tz))
+
+
+def plan_delete(client: GraphClient, list_id: str, task_id: str) -> Plan:
+    url = client.url(odata.p("me", "todo", "lists", list_id, "tasks", task_id))
+    return [PlannedRequest("DELETE", url, {}, None, expect="none")]
+
+
+def run_delete(client: GraphClient, list_id: str, task_id: str) -> None:
+    _run(client, plan_delete(client, list_id, task_id))
+
+
+def fetch_message_for_task(client: GraphClient, msg_id: str) -> dict:
+    """A minimal mail message view for `from-mail` (spec §8.15). Not shared with `graph/mail.py`."""
+    path = odata.p("me", "messages", msg_id)
+    return client.get(path, params={"$select": MESSAGE_SELECT})
+
+
+def plan_from_mail(
+    client: GraphClient,
+    list_id: str,
+    message: dict,
+    *,
+    title: str | None = None,
+    due: datetime | None = None,
+    importance: str | None = None,
+    tz: str,
+) -> Plan:
+    subject = message.get("subject") or ""
+    sender = render.fmt_person(message.get("from"))
+    received = message.get("receivedDateTime")
+    received_str = render.fmt_dt(received, tz) if received else "N/A"
+    content = f"From: {sender}\nReceived: {received_str}\n\n{message.get('bodyPreview') or ''}"
+    body: dict[str, Any] = {
+        "title": title or subject,
+        "body": {"content": content, "contentType": "text"},
+        "linkedResources": [
+            {
+                "webUrl": message.get("webLink"),
+                "applicationName": "Microsoft Outlook",
+                "displayName": subject,
+                "externalId": message.get("id"),
+            }
+        ],
+    }
+    if due is not None:
+        body["dueDateTime"] = render.to_graph_dtz(due, tz)
+    if importance is not None:
+        if importance not in IMPORTANCE_VALUES:
+            raise UsageError("USAGE", "--importance must be low, normal or high")
+        body["importance"] = importance
+    url = client.url(odata.p("me", "todo", "lists", list_id, "tasks"))
+    return [PlannedRequest("POST", url, dict(JSON_HEADERS), body)]
+
+
+def run_from_mail(client: GraphClient, list_id: str, message: dict, **opts: Any) -> dict:
+    return _run(client, plan_from_mail(client, list_id, message, **opts))

mgraphctl/graph/users.py

@@ -0,0 +1,85 @@
+"""Graph operations for users and the directory (spec §8.1, §8.5, §8.16).
+
+Pure: client and parameters in, Graph dicts or a `PageResult` out.
+"""
+
+from __future__ import annotations
+
+from mgraphctl import odata
+from mgraphctl.errors import UsageError
+from mgraphctl.http import GraphClient, PageResult
+from mgraphctl.resolve import looks_like_id, pick_unique
+
+ME_SELECT = (
+    "id,displayName,userPrincipalName,mail,jobTitle,department,officeLocation,"
+    "businessPhones,mobilePhone,preferredLanguage"
+)
+USER_SELECT = (
+    "id,displayName,userPrincipalName,mail,jobTitle,department,officeLocation,"
+    "businessPhones,mobilePhone"
+)
+USERS_SEARCH_SELECT = "id,displayName,userPrincipalName,mail,jobTitle,department,officeLocation"
+
+GROUPS_PATH = "/me/memberOf/microsoft.graph.group"
+UNIFIED_FILTER = "groupTypes/any(c:c eq 'Unified')"
+EVENTUAL = {"ConsistencyLevel": "eventual"}
+
+PAGE_SEARCH = 100
+PAGE_GROUPS = 999
+CAP = 999
+
+
+def user_path(ref: str) -> str:
+    """`/me` for the signed-in user, `/users/<ref>` (encoded) for anyone else."""
+    return "/me" if ref == "me" else odata.p("users", ref)
+
+
+def get_me(client: GraphClient, *, select: str = ME_SELECT) -> dict:
+    return client.get("/me", params={"$select": select})
+
+
+def get_user(client: GraphClient, ref: str, *, select: str = USER_SELECT) -> dict:
+    return client.get(user_path(ref), params={"$select": select})
+
+
+def search_users(client: GraphClient, q: str, *, limit: int, all_: bool) -> PageResult:
+    """Directory search. `$search` is tokenised, not substring, and needs ConsistencyLevel."""
+    term = f'"displayName:{q}" OR "mail:{q}"'
+    params = {"$search": term, "$count": True, "$select": USERS_SEARCH_SELECT}
+    return client.paginate(
+        "/users",
+        params=params,
+        headers=EVENTUAL,
+        limit=limit,
+        all_=all_,
+        cap=CAP,
+        page_size=PAGE_SEARCH,
+    )
+
+
+def list_unified_groups(client: GraphClient) -> list[dict]:
+    """Every Microsoft 365 group the signed-in user belongs to, id and name only."""
+    params = {"$filter": UNIFIED_FILTER, "$count": True, "$select": "id,displayName"}
+    return client.paginate(
+        GROUPS_PATH,
+        params=params,
+        headers=EVENTUAL,
+        limit=None,
+        all_=True,
+        cap=CAP,
+        page_size=PAGE_GROUPS,
+    ).items
+
+
+def resolve_user(client: GraphClient, value: str, *, can_search: bool) -> dict:
+    """Turn a UPN, id or display name into a user object (§6.6)."""
+    if looks_like_id(value, "user"):
+        return get_user(client, value)
+    if not can_search:
+        raise UsageError(
+            "USAGE",
+            f"{value!r} is not a UPN or id; directory search needs User.ReadBasic.All "
+            "(login --scopes extended)",
+        )
+    page = search_users(client, value, limit=50, all_=False)
+    return pick_unique(page.items, "displayName", value, what="user")

mgraphctl/html.py

@@ -0,0 +1,127 @@
+"""HTML → Markdown, plain text → HTML and WebVTT → text conversion (spec §6.2, §7.1)."""
+
+from __future__ import annotations
+
+import html as html_stdlib
+import re
+from collections.abc import Iterator
+from typing import Literal
+
+from bs4 import BeautifulSoup
+from markdownify import MarkdownConverter
+
+_HOSTED_CONTENT_RE = re.compile(r"/hostedContents/([^/]+)/\$value")
+_BLANK_LINES_RE = re.compile(r"\n{3,}")
+_PARAGRAPH_SPLIT_RE = re.compile(r"\n{2,}")
+_CUE_TIMING_RE = re.compile(r"^(\d{2}:\d{2}:\d{2})\.\d{3}\s*-->\s*\d{2}:\d{2}:\d{2}\.\d{3}")
+_VOICE_RE = re.compile(r"^<v\s+([^>]+)>(.*)</v>$", re.DOTALL)
+_TAG_RE = re.compile(r"<[^>]+>")
+
+_CONVERT_OPTIONS = {
+    "heading_style": "ATX",
+    "bullets": "-",
+    "escape_underscores": False,
+    "escape_asterisks": False,
+}
+
+
+class _TeamsConverter(MarkdownConverter):
+    """Renders Teams-specific markup: mentions, attachments, hosted images, system events."""
+
+    def convert_at(self, el, text, parent_tags):
+        return f"@{text}"
+
+    def convert_attachment(self, el, text, parent_tags):
+        name = el.attrs.get("name") or el.attrs.get("id") or ""
+        return f"[attachment: {name}]"
+
+    def convert_img(self, el, text, parent_tags):
+        src = el.attrs.get("src") or ""
+        match = _HOSTED_CONTENT_RE.search(src)
+        if match:
+            return f"[image: hostedContents/{match.group(1)}]"
+        return super().convert_img(el, text, parent_tags)
+
+    def convert_systemeventmessage(self, el, text, parent_tags):
+        return "[system event]"
+
+
+def to_markdown(html: str, mode: Literal["teams", "onenote", "mail"]) -> str:
+    """Convert a Graph HTML body to Markdown, applying Teams markers only in "teams" mode."""
+    soup = BeautifulSoup(html, "html.parser")
+    for tag in soup.find_all(("style", "script")):
+        tag.decompose()
+    converter_cls = _TeamsConverter if mode == "teams" else MarkdownConverter
+    text = converter_cls(**_CONVERT_OPTIONS).convert_soup(soup)
+    return _BLANK_LINES_RE.sub("\n\n", text).strip()
+
+
+def text_to_html(text: str) -> str:
+    """Convert plain text to escaped HTML: blank-line-separated `<p>`, `<br>` within a paragraph."""
+    paragraphs = _PARAGRAPH_SPLIT_RE.split(text)
+    rendered = []
+    for paragraph in paragraphs:
+        lines = paragraph.split("\n")
+        escaped = "<br>".join(html_stdlib.escape(line) for line in lines)
+        rendered.append(f"<p>{escaped}</p>")
+    return "".join(rendered)
+
+
+def _cues(vtt: str) -> Iterator[tuple[str, list[tuple[str | None, str]]]]:
+    """Yield `(timestamp, [(speaker | None, text), ...])` for every cue in a WebVTT document.
+
+    A cue can carry more than one line, and only some of them name a speaker with `<v Name>`,
+    so each line is kept as its own segment for the caller to render or merge.
+    """
+    for block in _PARAGRAPH_SPLIT_RE.split(vtt.strip()):
+        lines = [ln for ln in block.splitlines() if ln.strip()]
+        timing_idx = next(
+            (i for i, ln in enumerate(lines) if _CUE_TIMING_RE.match(ln.strip())), None
+        )
+        if timing_idx is None:
+            continue
+        stamp = _CUE_TIMING_RE.match(lines[timing_idx].strip()).group(1)
+        segments: list[tuple[str | None, str]] = []
+        for text_line in lines[timing_idx + 1 :]:
+            voice = _VOICE_RE.match(text_line.strip())
+            if voice:
+                # The name is kept exactly as the tag spelled it: `vtt_to_text` renders it
+                # verbatim, and only turn-merging, which has to compare names, normalises it.
+                name, content = voice.groups()
+                segments.append((name, _TAG_RE.sub("", content).strip()))
+            else:
+                segments.append((None, _TAG_RE.sub("", text_line).strip()))
+        yield stamp, segments
+
+
+def vtt_to_text(vtt: str) -> str:
+    """Convert a WebVTT transcript to `[HH:MM:SS] Speaker: text` lines, one per cue."""
+    lines_out = []
+    for stamp, segments in _cues(vtt):
+        rendered = [f"{name}: {text}" if name else text for name, text in segments]
+        lines_out.append(f"[{stamp}] {' '.join(rendered)}")
+    return "\n".join(lines_out)
+
+
+def vtt_to_speaker_turns(vtt: str) -> str:
+    """Convert a WebVTT transcript to speaker turns: `**Speaker:** text`, blank line between.
+
+    Consecutive cues from the same speaker are one turn — a transcript cues every few seconds,
+    so rendering one line per cue chops a single remark into a dozen fragments. A line with no
+    `<v>` tag continues the turn it falls inside.
+    """
+    turns: list[tuple[str | None, list[str]]] = []
+    for _, segments in _cues(vtt):
+        for raw_name, text in segments:
+            if not text:
+                continue
+            name = raw_name.strip() if raw_name is not None else None
+            speaker = name if name is not None else (turns[-1][0] if turns else None)
+            if turns and turns[-1][0] == speaker:
+                turns[-1][1].append(text)
+            else:
+                turns.append((speaker, [text]))
+    return "\n\n".join(
+        f"**{speaker}:** {' '.join(parts)}" if speaker else " ".join(parts)
+        for speaker, parts in turns
+    )