@tikomni/skills 0.1.0

package/skills/single-work-analysis/scripts/pipeline/asr/asr_pipeline.py

@@ -0,0 +1,1189 @@
+#!/usr/bin/env python3
+"""Shared ASR pipeline helpers for runner scripts."""
+
+import json
+import time
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse, urlunparse
+from typing import Any, Dict, List, Optional
+
+from scripts.core.tikomni_common import (
+    call_json_api,
+    deep_find_first,
+    extract_task_id,
+    extract_task_status,
+    extract_transcript_text,
+    is_terminal_status,
+    normalize_text,
+)
+
+U2_BATCH_SUBMIT_HARD_LIMIT = 100
+
+
+def clamp_u2_batch_submit_size(size: int, *, default: int = 50, hard_limit: int = U2_BATCH_SUBMIT_HARD_LIMIT) -> int:
+    try:
+        parsed = int(size)
+    except Exception:
+        parsed = int(default)
+    parsed = max(1, parsed)
+    return min(parsed, max(1, int(hard_limit)))
+
+
+def submit_u2_asr(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    video_url: str,
+) -> Dict[str, Any]:
+    return submit_u2_asr_batch(
+        base_url=base_url,
+        token=token,
+        timeout_ms=timeout_ms,
+        file_urls=[video_url],
+    )
+
+
+def submit_u2_asr_batch(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    file_urls: List[str],
+) -> Dict[str, Any]:
+    normalized_urls = normalize_media_candidates(file_urls)
+    limited_urls = normalized_urls[:U2_BATCH_SUBMIT_HARD_LIMIT]
+    return call_json_api(
+        base_url=base_url,
+        path="/api/u2/v1/services/audio/asr/transcription",
+        token=token,
+        method="POST",
+        timeout_ms=timeout_ms,
+        body={"input": {"file_urls": limited_urls}},
+    )
+
+
+def is_retriable_submit_failure(response: Dict[str, Any]) -> bool:
+    status_code = response.get("status_code")
+    if isinstance(status_code, str) and status_code.isdigit():
+        status_code = int(status_code)
+    if isinstance(status_code, (int, float)) and int(status_code) in {502, 503, 504}:
+        return True
+
+    error_reason = str(response.get("error_reason") or "").upper()
+    return "UPSTREAM_TIMEOUT" in error_reason or "TIMEOUT" in error_reason
+
+
+def submit_u2_asr_batch_with_retry(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    file_urls: List[str],
+    max_retries: int,
+    backoff_ms: int,
+) -> Dict[str, Any]:
+    retries = max(0, int(max_retries))
+    base_backoff = max(0, int(backoff_ms))
+    max_attempts = 1 + retries
+
+    normalized_urls = normalize_media_candidates(file_urls)
+    limited_urls = normalized_urls[:U2_BATCH_SUBMIT_HARD_LIMIT]
+    if not limited_urls:
+        return {
+            "submit_response": {
+                "ok": False,
+                "status_code": None,
+                "error_reason": "no_valid_file_urls",
+                "data": {},
+                "request_id": None,
+            },
+            "task_id": None,
+            "retry_chain": [],
+            "final_submit_status": "failed_no_valid_file_urls",
+            "file_urls": [],
+        }
+
+    retry_chain: List[Dict[str, Any]] = []
+    final_response: Dict[str, Any] = {}
+    final_task_id: Optional[str] = None
+    final_submit_status = "failed_unknown"
+
+    for attempt in range(1, max_attempts + 1):
+        wait_ms = 0 if attempt == 1 else base_backoff * (2 ** (attempt - 2))
+        if wait_ms > 0:
+            time.sleep(wait_ms / 1000.0)
+
+        submit_response = submit_u2_asr_batch(
+            base_url=base_url,
+            token=token,
+            timeout_ms=timeout_ms,
+            file_urls=limited_urls,
+        )
+        task_id = extract_task_id(submit_response.get("data"))
+        retriable = is_retriable_submit_failure(submit_response)
+
+        retry_chain.append(
+            {
+                "attempt": attempt,
+                "wait_ms": wait_ms,
+                "status_code": submit_response.get("status_code"),
+                "error_reason": submit_response.get("error_reason"),
+                "ok": submit_response.get("ok"),
+                "task_id": task_id,
+                "retriable": retriable,
+                "file_url_count": len(limited_urls),
+            }
+        )
+
+        final_response = submit_response
+        final_task_id = task_id
+
+        if submit_response.get("ok") and task_id:
+            final_submit_status = "success"
+            break
+
+        if submit_response.get("ok") and not task_id:
+            final_submit_status = "failed_missing_task_id"
+            break
+
+        if retriable and attempt < max_attempts:
+            final_submit_status = "retrying"
+            continue
+
+        final_submit_status = "failed_retries_exhausted" if retriable else "failed_non_retriable"
+        break
+
+    return {
+        "submit_response": final_response,
+        "task_id": final_task_id,
+        "retry_chain": retry_chain,
+        "final_submit_status": final_submit_status,
+        "file_urls": limited_urls,
+    }
+
+
+def submit_u2_asr_with_retry(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    video_url: str,
+    max_retries: int,
+    backoff_ms: int,
+) -> Dict[str, Any]:
+    return submit_u2_asr_batch_with_retry(
+        base_url=base_url,
+        token=token,
+        timeout_ms=timeout_ms,
+        file_urls=[video_url],
+        max_retries=max_retries,
+        backoff_ms=backoff_ms,
+    )
+
+
+def clean_transcript_text(raw_text: Any) -> str:
+    if raw_text is None:
+        return ""
+    return str(raw_text).strip()
+
+
+def extract_u2_task_metrics(payload: Any) -> Dict[str, Any]:
+    metrics = deep_find_first(payload, ["task_metrics", "metrics"])
+    return metrics if isinstance(metrics, dict) else {}
+
+
+def _safe_int(value: Any) -> int:
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, (int, float)):
+        return int(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return 0
+        try:
+            return int(float(text))
+        except Exception:
+            return 0
+    return 0
+
+
+def _status_upper(value: Any) -> str:
+    return str(value or "").strip().upper()
+
+
+def _is_success_status(status: str) -> bool:
+    return status in {"SUCCEEDED", "SUCCESS", "COMPLETED", "DONE"}
+
+
+def _is_failed_status(status: str) -> bool:
+    return status in {"FAILED", "FAILURE", "ERROR", "CANCELED", "CANCELLED"}
+
+
+def extract_platform_task_status(payload: Any) -> str:
+    status = deep_find_first(payload, ["platform_task_status"])
+    return _status_upper(status)
+
+
+def extract_pending_count(payload: Any) -> int:
+    return max(0, _safe_int(deep_find_first(payload, ["pending_count"])))
+
+
+def extract_u2_batch_result_items(payload: Any) -> List[Dict[str, Any]]:
+    found: Dict[str, Dict[str, Any]] = {}
+
+    stack: List[Any] = [payload]
+    while stack:
+        node = stack.pop(0)
+        if isinstance(node, dict):
+            raw_file_url = (
+                node.get("file_url")
+                or node.get("source_url")
+                or node.get("media_url")
+                or node.get("url")
+            )
+            file_url = normalize_media_url(str(raw_file_url or ""))
+            if file_url:
+                transcript = clean_transcript_text(
+                    node.get("transcript_text")
+                    or node.get("text")
+                    or node.get("transcript")
+                    or node.get("transcription")
+                    or node.get("content")
+                    or ""
+                )
+                if not transcript:
+                    transcript = clean_transcript_text(extract_transcript_text(node))
+
+                status = _status_upper(node.get("status") or node.get("task_status") or node.get("state"))
+                error_reason = str(node.get("error_reason") or node.get("error") or "").strip()
+                transcription_url = normalize_text(node.get("transcription_url"))
+                ok = _is_success_status(status) or bool(transcript) or bool(transcription_url)
+
+                candidate = {
+                    "file_url": file_url,
+                    "transcript_text": transcript,
+                    "task_status": status,
+                    "transcription_url": transcription_url,
+                    "error_reason": error_reason,
+                    "ok": ok,
+                }
+
+                existing = found.get(file_url)
+                if existing is None:
+                    found[file_url] = candidate
+                else:
+                    old_score = (
+                        1 if existing.get("ok") else 0,
+                        len(str(existing.get("transcript_text") or "")),
+                        1 if existing.get("transcription_url") else 0,
+                        1 if not existing.get("error_reason") else 0,
+                    )
+                    new_score = (
+                        1 if candidate.get("ok") else 0,
+                        len(str(candidate.get("transcript_text") or "")),
+                        1 if candidate.get("transcription_url") else 0,
+                        1 if not candidate.get("error_reason") else 0,
+                    )
+                    if new_score > old_score:
+                        found[file_url] = candidate
+
+            for value in node.values():
+                if isinstance(value, (dict, list)):
+                    stack.append(value)
+        elif isinstance(node, list):
+            for item in node:
+                if isinstance(item, (dict, list)):
+                    stack.append(item)
+
+    return list(found.values())
+
+
+def map_u2_batch_results_by_file_url(payload: Any) -> Dict[str, Dict[str, Any]]:
+    mapped: Dict[str, Dict[str, Any]] = {}
+    for item in extract_u2_batch_result_items(payload):
+        file_url = normalize_media_url(item.get("file_url"))
+        if not file_url:
+            continue
+        mapped[file_url] = item
+    return mapped
+
+
+def _parse_non_negative_item_index(value: Any) -> Optional[int]:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value >= 0 else None
+    if isinstance(value, float):
+        if value < 0 or not value.is_integer():
+            return None
+        return int(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text or not text.isdigit():
+            return None
+        return int(text)
+    return None
+
+
+def map_u2_batch_results_by_item_index(payload: Any) -> Dict[int, Dict[str, Any]]:
+    mapped: Dict[int, Dict[str, Any]] = {}
+    stack: List[Any] = [payload]
+
+    while stack:
+        node = stack.pop(0)
+        if isinstance(node, dict):
+            item_index_raw = node.get("item_index")
+            item_index = _parse_non_negative_item_index(item_index_raw)
+            if item_index is not None:
+                transcript = clean_transcript_text(
+                    node.get("transcript_text")
+                    or node.get("text")
+                    or node.get("transcript")
+                    or node.get("transcription")
+                    or node.get("content")
+                    or ""
+                )
+                if not transcript:
+                    transcript = clean_transcript_text(extract_transcript_text(node))
+
+                status = _status_upper(node.get("task_status") or node.get("status") or node.get("state"))
+                error_reason = str(node.get("error_reason") or node.get("error") or "").strip()
+                transcription_url = normalize_text(node.get("transcription_url"))
+                ok = _is_success_status(status) or bool(transcript) or bool(transcription_url)
+
+                candidate = {
+                    "item_index": item_index,
+                    "transcript_text": transcript,
+                    "task_status": status,
+                    "error_reason": error_reason,
+                    "transcription_url": transcription_url,
+                    "ok": ok,
+                }
+
+                existing = mapped.get(item_index)
+                if existing is None:
+                    mapped[item_index] = candidate
+                else:
+                    old_score = (
+                        1 if existing.get("ok") else 0,
+                        len(str(existing.get("transcript_text") or "")),
+                        1 if existing.get("transcription_url") else 0,
+                        1 if not existing.get("error_reason") else 0,
+                    )
+                    new_score = (
+                        1 if candidate.get("ok") else 0,
+                        len(str(candidate.get("transcript_text") or "")),
+                        1 if candidate.get("transcription_url") else 0,
+                        1 if not candidate.get("error_reason") else 0,
+                    )
+                    if new_score > old_score:
+                        mapped[item_index] = candidate
+
+            for value in node.values():
+                if isinstance(value, (dict, list)):
+                    stack.append(value)
+        elif isinstance(node, list):
+            for item in node:
+                if isinstance(item, (dict, list)):
+                    stack.append(item)
+
+    return mapped
+
+
+def _extract_transcript_from_transcription_payload(payload: Any) -> str:
+    if isinstance(payload, str):
+        text = clean_transcript_text(payload)
+        if text:
+            return text
+        try:
+            payload = json.loads(payload)
+        except Exception:
+            return ""
+
+    transcript = clean_transcript_text(deep_find_first(payload, ["full_text"]))
+    if transcript:
+        return transcript
+
+    transcript = clean_transcript_text(extract_transcript_text(payload))
+    if transcript:
+        return transcript
+
+    sentences = deep_find_first(payload, ["sentences"])
+    if isinstance(sentences, list):
+        lines: List[str] = []
+        for sentence in sentences:
+            if not isinstance(sentence, dict):
+                continue
+            line = clean_transcript_text(
+                sentence.get("text") or sentence.get("sentence") or sentence.get("content")
+            )
+            if line:
+                lines.append(line)
+        if lines:
+            return "\n".join(lines)
+
+    return ""
+
+
+def fetch_transcription_text_by_url(*, transcription_url: str, timeout_ms: int) -> Dict[str, Any]:
+    url = normalize_media_url(transcription_url)
+    if not url:
+        return {
+            "ok": False,
+            "transcription_url": "",
+            "error_reason": "transcription_url_missing",
+            "transcript_text": "",
+        }
+    if not (url.startswith("http://") or url.startswith("https://")):
+        return {
+            "ok": False,
+            "transcription_url": url,
+            "error_reason": "transcription_url_invalid",
+            "transcript_text": "",
+        }
+
+    request = urllib.request.Request(url=url, method="GET", headers={"Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=max(timeout_ms / 1000.0, 1.0)) as response:
+            raw_text = response.read().decode("utf-8", errors="replace")
+    except urllib.error.URLError as error:
+        return {
+            "ok": False,
+            "transcription_url": url,
+            "error_reason": f"transcription_fetch_failed:{normalize_text(getattr(error, 'reason', error)) or 'unknown'}",
+            "transcript_text": "",
+        }
+    except Exception as error:
+        return {
+            "ok": False,
+            "transcription_url": url,
+            "error_reason": f"transcription_fetch_failed:{normalize_text(error) or 'unknown'}",
+            "transcript_text": "",
+        }
+
+    payload: Any = raw_text
+    try:
+        payload = json.loads(raw_text)
+    except Exception:
+        payload = raw_text
+
+    transcript = _extract_transcript_from_transcription_payload(payload)
+    if transcript:
+        return {
+            "ok": True,
+            "transcription_url": url,
+            "error_reason": "",
+            "transcript_text": transcript,
+        }
+
+    return {
+        "ok": False,
+        "transcription_url": url,
+        "error_reason": "transcription_payload_empty",
+        "transcript_text": "",
+    }
+
+
+def hydrate_u2_batch_results_from_transcription_urls(
+    *,
+    mapped_results: Dict[str, Dict[str, Any]],
+    timeout_ms: int,
+) -> Dict[str, Dict[str, Any]]:
+    hydrated: Dict[str, Dict[str, Any]] = {}
+    fetch_timeout_ms = max(1000, min(int(timeout_ms), 15000))
+
+    for file_url, item in mapped_results.items():
+        if not isinstance(item, dict):
+            continue
+
+        candidate = dict(item)
+        status = _status_upper(candidate.get("task_status"))
+        transcript = clean_transcript_text(candidate.get("transcript_text"))
+        transcription_url = normalize_text(candidate.get("transcription_url"))
+
+        if not transcript and _is_success_status(status) and transcription_url:
+            fetch_result = fetch_transcription_text_by_url(
+                transcription_url=transcription_url,
+                timeout_ms=fetch_timeout_ms,
+            )
+            fetched_text = clean_transcript_text(fetch_result.get("transcript_text"))
+            candidate["transcription_fetch"] = {
+                "ok": bool(fetch_result.get("ok")),
+                "error_reason": fetch_result.get("error_reason"),
+            }
+            if fetched_text:
+                transcript = fetched_text
+                candidate["transcript_text"] = fetched_text
+            elif not candidate.get("error_reason"):
+                candidate["error_reason"] = fetch_result.get("error_reason") or "transcription_payload_empty"
+
+        candidate["task_status"] = status
+        candidate["transcription_url"] = transcription_url
+        candidate["transcript_text"] = transcript
+        candidate["ok"] = bool(candidate.get("ok") or transcript)
+        hydrated[file_url] = candidate
+
+    return hydrated
+
+
+def build_u2_batch_progress(*, payload: Any, expected_total: int = 0) -> Dict[str, Any]:
+    metrics_raw = extract_u2_task_metrics(payload)
+    metrics = {str(key).strip().upper(): value for key, value in metrics_raw.items()} if isinstance(metrics_raw, dict) else {}
+
+    metrics_total = _safe_int(metrics.get("TOTAL") or metrics.get("TASK_TOTAL") or metrics.get("COUNT"))
+    metrics_succeeded = _safe_int(metrics.get("SUCCEEDED") or metrics.get("SUCCESS"))
+    metrics_failed = (
+        _safe_int(metrics.get("FAILED"))
+        + _safe_int(metrics.get("FAILURE"))
+        + _safe_int(metrics.get("ERROR"))
+        + _safe_int(metrics.get("CANCELED"))
+        + _safe_int(metrics.get("CANCELLED"))
+    )
+    metrics_completed = metrics_succeeded + metrics_failed
+
+    provider_total = _safe_int(deep_find_first(payload, ["input_count", "total_count"]))
+    provider_succeeded = _safe_int(deep_find_first(payload, ["succeeded_count"]))
+    provider_failed = _safe_int(deep_find_first(payload, ["failed_count"]))
+    provider_pending = max(0, _safe_int(deep_find_first(payload, ["pending_count"])))
+    provider_completed = provider_succeeded + provider_failed
+    provider_status = extract_platform_task_status(payload)
+
+    mapped_results = map_u2_batch_results_by_file_url(payload)
+    result_total = len(mapped_results)
+    result_succeeded = 0
+    result_failed = 0
+
+    for item in mapped_results.values():
+        status = _status_upper(item.get("task_status"))
+        transcript = clean_transcript_text(item.get("transcript_text"))
+        if _is_success_status(status) or transcript:
+            result_succeeded += 1
+        elif _is_failed_status(status):
+            result_failed += 1
+
+    result_completed = result_succeeded + result_failed
+
+    target_total = metrics_total if metrics_total > 0 else (provider_total if provider_total > 0 else max(0, int(expected_total or 0)))
+    complete_by_metrics = target_total > 0 and metrics_completed >= target_total
+    complete_by_provider_counts = target_total > 0 and provider_pending == 0 and provider_completed >= target_total
+    complete_by_provider_status = provider_pending == 0 and provider_status in {"SUCCEEDED", "PARTIAL_SUCCEEDED", "FAILED"}
+    complete_by_results = target_total > 0 and result_completed >= target_total
+
+    completion_basis = "pending"
+    if complete_by_metrics:
+        completion_basis = "task_metrics"
+    elif complete_by_provider_counts or complete_by_provider_status:
+        completion_basis = "platform_status"
+    elif complete_by_results:
+        completion_basis = "results"
+
+    return {
+        "expected_total": max(0, int(expected_total or 0)),
+        "target_total": target_total,
+        "metrics_total": metrics_total,
+        "metrics_succeeded": metrics_succeeded,
+        "metrics_failed": metrics_failed,
+        "metrics_completed": metrics_completed,
+        "provider_total": provider_total,
+        "provider_succeeded": provider_succeeded,
+        "provider_failed": provider_failed,
+        "provider_pending": provider_pending,
+        "platform_task_status": provider_status,
+        "results_total": result_total,
+        "results_succeeded": result_succeeded,
+        "results_failed": result_failed,
+        "results_completed": result_completed,
+        "complete": bool(complete_by_metrics or complete_by_provider_counts or complete_by_provider_status or complete_by_results),
+        "completion_basis": completion_basis,
+        "metrics": metrics_raw if isinstance(metrics_raw, dict) else {},
+    }
+
+
+def poll_u2_task_core(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    task_id: str,
+    poll_interval_sec: float,
+    max_polls: int,
+    require_batch_complete: bool = False,
+    expected_total: int = 0,
+) -> Dict[str, Any]:
+    trace = []
+    last_request_id = None
+
+    last_status = "UNKNOWN"
+    last_payload: Any = {}
+    last_batch_results: Dict[str, Dict[str, Any]] = {}
+    last_metrics: Dict[str, Any] = {}
+    last_progress: Dict[str, Any] = {
+        "expected_total": max(0, int(expected_total or 0)),
+        "target_total": 0,
+        "complete": False,
+        "completion_basis": "pending",
+    }
+
+    for attempt in range(1, max_polls + 1):
+        response = call_json_api(
+            base_url=base_url,
+            path=f"/api/u2/v1/tasks/{task_id}",
+            token=token,
+            method="POST",
+            timeout_ms=timeout_ms,
+        )
+
+        payload = response.get("data")
+        status = extract_task_status(payload)
+        platform_status = extract_platform_task_status(payload)
+        pending_count = extract_pending_count(payload)
+        last_request_id = response.get("request_id") or last_request_id
+
+        metrics = extract_u2_task_metrics(payload)
+        batch_results = map_u2_batch_results_by_file_url(payload)
+        batch_progress = build_u2_batch_progress(payload=payload, expected_total=expected_total)
+
+        effective_status = platform_status or status
+        last_status = effective_status or last_status
+        last_payload = payload
+        last_batch_results = batch_results
+        last_metrics = metrics if isinstance(metrics, dict) else {}
+        last_progress = batch_progress
+
+        trace.append(
+            {
+                "attempt": attempt,
+                "status_code": response.get("status_code"),
+                "task_status": status,
+                "platform_task_status": platform_status,
+                "pending_count": pending_count,
+                "request_id": response.get("request_id"),
+                "error_reason": response.get("error_reason"),
+                "batch_progress": batch_progress,
+            }
+        )
+
+        if not response.get("ok"):
+            if attempt < max_polls:
+                time.sleep(max(poll_interval_sec, 0.2))
+                continue
+            return {
+                "ok": False,
+                "task_id": task_id,
+                "task_status": status or "UNKNOWN",
+                "request_id": last_request_id,
+                "error_reason": response.get("error_reason") or "u2_poll_http_error",
+                "raw_task": payload,
+                "task_metrics": last_metrics,
+                "batch_results": batch_results,
+                "batch_progress": batch_progress,
+                "batch_complete": bool(batch_progress.get("complete")),
+                "trace": trace,
+            }
+
+        status_terminal = is_terminal_status(status)
+        platform_terminal = pending_count == 0 and platform_status in {"SUCCEEDED", "PARTIAL_SUCCEEDED", "FAILED"}
+        task_complete = status_terminal or platform_terminal
+        batch_complete = bool(batch_progress.get("complete")) if require_batch_complete else task_complete
+
+        if require_batch_complete and not batch_complete:
+            if attempt < max_polls:
+                time.sleep(max(poll_interval_sec, 0.2))
+                continue
+            return {
+                "ok": False,
+                "task_id": task_id,
+                "task_status": effective_status or "UNKNOWN",
+                "request_id": last_request_id,
+                "error_reason": "u2_batch_incomplete_timeout",
+                "raw_task": payload,
+                "task_metrics": last_metrics,
+                "batch_results": batch_results,
+                "batch_progress": batch_progress,
+                "batch_complete": False,
+                "trace": trace,
+            }
+
+        if task_complete or batch_complete:
+            success_signal = (
+                platform_status == "SUCCEEDED" and pending_count == 0
+            ) or _is_success_status(status)
+            transcript = extract_transcript_text(payload) if success_signal else ""
+            return {
+                "ok": bool(success_signal),
+                "task_id": task_id,
+                "task_status": effective_status or status,
+                "platform_task_status": platform_status,
+                "pending_count": pending_count,
+                "request_id": last_request_id,
+                "error_reason": None if success_signal else (None if batch_complete and require_batch_complete else "u2_task_failed"),
+                "transcript_text": clean_transcript_text(transcript),
+                "raw_task": payload,
+                "task_metrics": last_metrics,
+                "batch_results": batch_results,
+                "batch_progress": batch_progress,
+                "batch_complete": bool(batch_complete),
+                "trace": trace,
+            }
+
+        time.sleep(max(poll_interval_sec, 0.2))
+
+    timeout_reason = "u2_batch_incomplete_timeout" if require_batch_complete else "u2_poll_timeout"
+    return {
+        "ok": False,
+        "task_id": task_id,
+        "task_status": last_status or "TIMEOUT",
+        "request_id": last_request_id,
+        "error_reason": timeout_reason,
+        "raw_task": last_payload,
+        "task_metrics": last_metrics,
+        "batch_results": last_batch_results,
+        "batch_progress": last_progress,
+        "batch_complete": bool(last_progress.get("complete")) if require_batch_complete else False,
+        "trace": trace,
+    }
+
+
+def normalize_media_url(url: str) -> str:
+    text = str(url or "").strip()
+    if not text:
+        return ""
+    try:
+        parsed = urlparse(text)
+    except Exception:
+        return text
+
+    scheme = (parsed.scheme or "").lower()
+    if scheme == "http":
+        parsed = parsed._replace(scheme="https")
+    return urlunparse(parsed)
+
+
+def is_valid_u2_media_candidate(url: str) -> bool:
+    lower = str(url or "").lower()
+    if not (lower.startswith("http://") or lower.startswith("https://")):
+        return False
+    image_tokens = [".jpg", ".jpeg", ".png", ".webp", "imageview2", "imagemogr2", "redimage", "frame/"]
+    if any(token in lower for token in image_tokens):
+        return False
+    media_tokens = [".mp4", ".m3u8", ".m4a", ".mp3", "video", "stream", "audio", "vod"]
+    return any(token in lower for token in media_tokens)
+
+
+def normalize_media_candidates(candidates: List[str]) -> List[str]:
+    normalized: List[str] = []
+    seen = set()
+    for raw in candidates or []:
+        url = normalize_media_url(raw)
+        if not url or url in seen:
+            continue
+        seen.add(url)
+        normalized.append(url)
+    return normalized
+
+
+def run_u2_asr_candidates_with_timeout_retry(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    candidates: List[str],
+    submit_max_retries: int,
+    submit_backoff_ms: int,
+    poll_interval_sec: float,
+    max_polls: int,
+    timeout_retry_enabled: bool = True,
+    timeout_retry_max_retries: int = 3,
+) -> Dict[str, Any]:
+    normalized_candidates = normalize_media_candidates(candidates)
+    attempts: List[Dict[str, Any]] = []
+
+    final_bundle: Dict[str, Any] = {
+        "submit_bundle": {},
+        "poll_result": {"ok": False, "task_status": "UNKNOWN", "error_reason": "no_candidates"},
+        "rounds": [],
+        "timeout_retry": {"enabled": bool(timeout_retry_enabled), "configured_max_retries": max(0, min(3, int(timeout_retry_max_retries))), "triggered": False, "result": "not_triggered"},
+    }
+    chosen_url: Optional[str] = None
+
+    for index, candidate in enumerate(normalized_candidates, start=1):
+        valid = is_valid_u2_media_candidate(candidate)
+        if not valid:
+            attempts.append({
+                "index": index,
+                "candidate": candidate,
+                "valid": False,
+                "result": "skipped_non_media_candidate",
+            })
+            continue
+
+        bundle = run_u2_asr_with_timeout_retry(
+            base_url=base_url,
+            token=token,
+            timeout_ms=timeout_ms,
+            video_url=candidate,
+            submit_max_retries=submit_max_retries,
+            submit_backoff_ms=submit_backoff_ms,
+            poll_interval_sec=poll_interval_sec,
+            max_polls=max_polls,
+            timeout_retry_enabled=timeout_retry_enabled,
+            timeout_retry_max_retries=timeout_retry_max_retries,
+        )
+        poll_result = bundle.get("poll_result", {})
+        error_reason = str(poll_result.get("error_reason") or "")
+        ok = bool(poll_result.get("ok"))
+
+        attempts.append({
+            "index": index,
+            "candidate": candidate,
+            "valid": True,
+            "ok": ok,
+            "error_reason": error_reason,
+            "task_status": poll_result.get("task_status"),
+        })
+
+        final_bundle = bundle
+        chosen_url = candidate
+        if ok:
+            break
+
+        if error_reason == "INVALID_SOURCE_URL":
+            continue
+
+    final_bundle["candidate_attempts"] = attempts
+    final_bundle["chosen_candidate"] = chosen_url
+    final_bundle["normalized_candidates"] = normalized_candidates
+    return final_bundle
+
+
+def run_u2_asr_batch_with_timeout_retry(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    file_urls: List[str],
+    submit_max_retries: int,
+    submit_backoff_ms: int,
+    poll_interval_sec: float,
+    max_polls: int,
+    timeout_retry_enabled: bool = True,
+    timeout_retry_max_retries: int = 3,
+) -> Dict[str, Any]:
+    normalized_urls = normalize_media_candidates(file_urls)
+    limited_urls = normalized_urls[:U2_BATCH_SUBMIT_HARD_LIMIT]
+
+    conservative_retries = max(0, min(3, int(timeout_retry_max_retries)))
+    retries = conservative_retries if timeout_retry_enabled else 0
+    max_rounds = 1 + retries
+
+    rounds: List[Dict[str, Any]] = []
+    final_submit_bundle: Dict[str, Any] = {}
+    final_poll_result: Dict[str, Any] = {
+        "ok": False,
+        "task_status": "UNKNOWN",
+        "error_reason": "u2_submit_failed_or_missing_task_id",
+        "task_metrics": {},
+        "batch_results": {},
+    }
+    timeout_retry_triggered = False
+    timeout_retry_result = "not_triggered"
+
+    if not limited_urls:
+        return {
+            "submit_bundle": {
+                "submit_response": {"ok": False, "error_reason": "no_valid_file_urls"},
+                "task_id": None,
+                "retry_chain": [],
+                "final_submit_status": "failed_no_valid_file_urls",
+                "file_urls": [],
+            },
+            "poll_result": {
+                "ok": False,
+                "task_status": "UNKNOWN",
+                "error_reason": "no_valid_file_urls",
+                "task_metrics": {},
+                "batch_results": {},
+            },
+            "rounds": [],
+            "timeout_retry": {
+                "enabled": bool(timeout_retry_enabled),
+                "configured_max_retries": conservative_retries,
+                "triggered": False,
+                "result": "not_triggered",
+            },
+            "normalized_file_urls": [],
+            "mapped_results": {},
+            "result_items": [],
+            "task_metrics": {},
+        }
+
+    for round_index in range(1, max_rounds + 1):
+        submit_bundle = submit_u2_asr_batch_with_retry(
+            base_url=base_url,
+            token=token,
+            timeout_ms=timeout_ms,
+            file_urls=limited_urls,
+            max_retries=submit_max_retries,
+            backoff_ms=submit_backoff_ms,
+        )
+        submit_response = submit_bundle.get("submit_response", {})
+        task_id = submit_bundle.get("task_id")
+
+        poll_result: Dict[str, Any]
+        if submit_response.get("ok") and task_id:
+            poll_result = poll_u2_task_core(
+                base_url=base_url,
+                token=token,
+                timeout_ms=timeout_ms,
+                task_id=str(task_id),
+                poll_interval_sec=poll_interval_sec,
+                max_polls=max_polls,
+                require_batch_complete=True,
+                expected_total=len(limited_urls),
+            )
+        else:
+            poll_result = {
+                "ok": False,
+                "task_id": task_id,
+                "task_status": "UNKNOWN",
+                "request_id": submit_response.get("request_id"),
+                "error_reason": submit_response.get("error_reason") or "u2_submit_failed_or_missing_task_id",
+                "task_metrics": {},
+                "batch_results": {},
+                "batch_progress": {
+                    "expected_total": len(limited_urls),
+                    "target_total": len(limited_urls),
+                    "complete": False,
+                    "completion_basis": "pending",
+                },
+                "batch_complete": False,
+                "trace": [],
+            }
+
+        rounds.append(
+            {
+                "round": round_index,
+                "submit": {
+                    "task_id": task_id,
+                    "final_submit_status": submit_bundle.get("final_submit_status"),
+                    "request_id": submit_response.get("request_id"),
+                    "status_code": submit_response.get("status_code"),
+                    "ok": submit_response.get("ok"),
+                    "error_reason": submit_response.get("error_reason"),
+                    "retry_chain": submit_bundle.get("retry_chain", []),
+                    "file_url_count": len(limited_urls),
+                },
+                "poll": {
+                    "task_id": poll_result.get("task_id") or task_id,
+                    "task_status": poll_result.get("task_status"),
+                    "request_id": poll_result.get("request_id"),
+                    "ok": poll_result.get("ok"),
+                    "error_reason": poll_result.get("error_reason"),
+                    "attempts": len(poll_result.get("trace", [])),
+                    "task_metrics": poll_result.get("task_metrics", {}),
+                    "batch_complete": bool(poll_result.get("batch_complete")),
+                    "batch_progress": poll_result.get("batch_progress", {}),
+                },
+            }
+        )
+
+        final_submit_bundle = submit_bundle
+        final_poll_result = poll_result
+
+        if poll_result.get("error_reason") in {"u2_poll_timeout", "u2_batch_incomplete_timeout"} and round_index < max_rounds:
+            timeout_retry_triggered = True
+            timeout_retry_result = "retrying"
+            continue
+
+        break
+
+    if final_poll_result.get("ok"):
+        timeout_retry_result = "retry_succeeded" if timeout_retry_triggered else "not_needed"
+    elif final_poll_result.get("error_reason") in {"u2_poll_timeout", "u2_batch_incomplete_timeout"}:
+        timeout_retry_result = "retry_timeout_exhausted" if timeout_retry_triggered else "timeout_no_retry"
+    elif timeout_retry_triggered:
+        timeout_retry_result = "retry_failed_non_timeout"
+    else:
+        timeout_retry_result = "not_triggered"
+
+    raw_task_payload = final_poll_result.get("raw_task")
+    mapped_results = map_u2_batch_results_by_file_url(raw_task_payload)
+
+    index_mapped = map_u2_batch_results_by_item_index(raw_task_payload)
+    for item_index, item in index_mapped.items():
+        if item_index < 0 or item_index >= len(limited_urls):
+            continue
+        file_url = normalize_media_url(limited_urls[item_index])
+        if not file_url:
+            continue
+
+        candidate = {
+            "file_url": file_url,
+            "transcript_text": clean_transcript_text(item.get("transcript_text")),
+            "task_status": _status_upper(item.get("task_status")),
+            "error_reason": str(item.get("error_reason") or "").strip(),
+            "transcription_url": normalize_text(item.get("transcription_url")),
+            "ok": bool(item.get("ok")),
+        }
+
+        existing = mapped_results.get(file_url)
+        if existing is None:
+            mapped_results[file_url] = candidate
+            continue
+
+        old_score = (
+            1 if existing.get("ok") else 0,
+            len(str(existing.get("transcript_text") or "")),
+            1 if existing.get("transcription_url") else 0,
+            1 if not existing.get("error_reason") else 0,
+        )
+        new_score = (
+            1 if candidate.get("ok") else 0,
+            len(str(candidate.get("transcript_text") or "")),
+            1 if candidate.get("transcription_url") else 0,
+            1 if not candidate.get("error_reason") else 0,
+        )
+        if new_score > old_score:
+            mapped_results[file_url] = candidate
+
+    mapped_results = hydrate_u2_batch_results_from_transcription_urls(
+        mapped_results=mapped_results,
+        timeout_ms=timeout_ms,
+    )
+    result_items = list(mapped_results.values())
+
+    return {
+        "submit_bundle": final_submit_bundle,
+        "poll_result": final_poll_result,
+        "rounds": rounds,
+        "timeout_retry": {
+            "enabled": bool(timeout_retry_enabled),
+            "configured_max_retries": conservative_retries,
+            "triggered": timeout_retry_triggered,
+            "result": timeout_retry_result,
+        },
+        "normalized_file_urls": limited_urls,
+        "mapped_results": mapped_results,
+        "result_items": result_items,
+        "task_metrics": final_poll_result.get("task_metrics") if isinstance(final_poll_result.get("task_metrics"), dict) else extract_u2_task_metrics(raw_task_payload),
+        "batch_progress": final_poll_result.get("batch_progress") if isinstance(final_poll_result.get("batch_progress"), dict) else build_u2_batch_progress(payload=raw_task_payload, expected_total=len(limited_urls)),
+        "batch_complete": bool(final_poll_result.get("batch_complete")),
+    }
+
+
+def run_u2_asr_with_timeout_retry(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    video_url: str,
+    submit_max_retries: int,
+    submit_backoff_ms: int,
+    poll_interval_sec: float,
+    max_polls: int,
+    timeout_retry_enabled: bool = True,
+    timeout_retry_max_retries: int = 3,
+) -> Dict[str, Any]:
+    video_url = normalize_media_url(video_url)
+    conservative_retries = max(0, min(3, int(timeout_retry_max_retries)))
+    retries = conservative_retries if timeout_retry_enabled else 0
+    max_rounds = 1 + retries
+
+    rounds: List[Dict[str, Any]] = []
+    final_submit_bundle: Dict[str, Any] = {}
+    final_poll_result: Dict[str, Any] = {
+        "ok": False,
+        "task_status": "UNKNOWN",
+        "error_reason": "u2_submit_failed_or_missing_task_id",
+    }
+    timeout_retry_triggered = False
+    timeout_retry_result = "not_triggered"
+
+    for round_index in range(1, max_rounds + 1):
+        submit_bundle = submit_u2_asr_with_retry(
+            base_url=base_url,
+            token=token,
+            timeout_ms=timeout_ms,
+            video_url=video_url,
+            max_retries=submit_max_retries,
+            backoff_ms=submit_backoff_ms,
+        )
+        submit_response = submit_bundle.get("submit_response", {})
+        task_id = submit_bundle.get("task_id")
+
+        poll_result: Dict[str, Any]
+        if submit_response.get("ok") and task_id:
+            poll_result = poll_u2_task_core(
+                base_url=base_url,
+                token=token,
+                timeout_ms=timeout_ms,
+                task_id=str(task_id),
+                poll_interval_sec=poll_interval_sec,
+                max_polls=max_polls,
+            )
+        else:
+            poll_result = {
+                "ok": False,
+                "task_id": task_id,
+                "task_status": "UNKNOWN",
+                "request_id": submit_response.get("request_id"),
+                "error_reason": submit_response.get("error_reason") or "u2_submit_failed_or_missing_task_id",
+                "trace": [],
+            }
+
+        rounds.append(
+            {
+                "round": round_index,
+                "submit": {
+                    "task_id": task_id,
+                    "final_submit_status": submit_bundle.get("final_submit_status"),
+                    "request_id": submit_response.get("request_id"),
+                    "status_code": submit_response.get("status_code"),
+                    "ok": submit_response.get("ok"),
+                    "error_reason": submit_response.get("error_reason"),
+                    "retry_chain": submit_bundle.get("retry_chain", []),
+                },
+                "poll": {
+                    "task_id": poll_result.get("task_id") or task_id,
+                    "task_status": poll_result.get("task_status"),
+                    "request_id": poll_result.get("request_id"),
+                    "ok": poll_result.get("ok"),
+                    "error_reason": poll_result.get("error_reason"),
+                    "attempts": len(poll_result.get("trace", [])),
+                },
+            }
+        )
+
+        final_submit_bundle = submit_bundle
+        final_poll_result = poll_result
+
+        if poll_result.get("error_reason") == "u2_poll_timeout" and round_index < max_rounds:
+            timeout_retry_triggered = True
+            timeout_retry_result = "retrying"
+            continue
+
+        break
+
+    if final_poll_result.get("ok"):
+        timeout_retry_result = "retry_succeeded" if timeout_retry_triggered else "not_needed"
+    elif final_poll_result.get("error_reason") == "u2_poll_timeout":
+        timeout_retry_result = "retry_timeout_exhausted" if timeout_retry_triggered else "timeout_no_retry"
+    elif timeout_retry_triggered:
+        timeout_retry_result = "retry_failed_non_timeout"
+    else:
+        timeout_retry_result = "not_triggered"
+
+    return {
+        "submit_bundle": final_submit_bundle,
+        "poll_result": final_poll_result,
+        "rounds": rounds,
+        "timeout_retry": {
+            "enabled": bool(timeout_retry_enabled),
+            "configured_max_retries": conservative_retries,
+            "triggered": timeout_retry_triggered,
+            "result": timeout_retry_result,
+        },
+    }