"""
D3RO-VOICE STT Sidecar (FastAPI HTTP 서버)
faster-whisper + CTranslate2만 사용. torch/pyannote 비의존으로 슬림 배포.

사용법:
    python main.py --port 18765 --models-dir <path>

엔드포인트:
    GET  /health          - 헬스체크
    POST /load            - Whisper 모델 로딩
    POST /transcribe      - 오디오 전사 (multipart)
    POST /download        - 모델 다운로드 시작 (백그라운드)
    GET  /download/status - 다운로드 진행률 조회
    POST /download/cancel - 다운로드 취소
    GET  /uia/focus       - 포커스 입력 요소 UIA 스냅샷 (제안/학습용)
    POST /shutdown        - 서버 종료

주: 화자 구분(diarization)은 Phase 15.5에서 LLM 추정 경로가 primary이며,
pyannote 기반 고정밀 화자 구분은 추후 서버 사이드 API로 제공될 예정.
"""

from __future__ import annotations

import argparse
import asyncio
import fnmatch
import logging
import os
import signal
import sys
import threading
import time
from contextlib import asynccontextmanager
from pathlib import Path
from typing import AsyncGenerator

import numpy as np
import uvicorn
from fastapi import FastAPI, File, Form, Request, UploadFile
from fastapi.responses import JSONResponse

from device_policy import (
    CPU_CHOICE,
    DeviceChoice,
    choose_gpu_device,
    is_gpu_runtime_error,
    load_with_fallback,
)

# ── 로깅 설정 ──────────────────────────────────────────────

# Windows에서 파이프로 연결되면 Python이 로케일(cp949) 인코딩으로 출력해
# 메인 프로세스의 UTF-8 로그가 깨진다. 명시적으로 UTF-8로 고정한다.
for _stream in (sys.stdout, sys.stderr):
    try:
        _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
    except (AttributeError, ValueError):
        pass

logging.basicConfig(
    level=logging.INFO,
    format="[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    stream=sys.stdout,
)
logger = logging.getLogger("sidecar")

# ── 전역 상태 ──────────────────────────────────────────────

_model: "WhisperModel | None" = None
_model_id: str | None = None
# 보조 모델 (실시간 자막 등 받아쓰기와 다른 모델). 최대 1개.
_aux_models: "dict[str, WhisperModel]" = {}
_gpu_available: bool = False
# GPU 로 올릴 때 쓸 장치/정밀도. GPU 가 없거나 검증에 실패하면 None.
_gpu_choice: DeviceChoice | None = None
# 로딩된 모델별 실제 장치 (primary/aux 는 같은 model_id 를 동시에 들지 않는다).
_model_devices: dict[str, DeviceChoice] = {}
_server: uvicorn.Server | None = None
_models_dir: Path | None = None

# 모델 추론·로딩은 한 번에 하나만 돈다(모델 교체와 전사가 겹치지 않게). 무거운 작업은
# asyncio.to_thread 로 돌려, 긴 전사·로딩 중에도 /health · /uia/focus · /download/status 가 응답한다.
# (예전엔 async 핸들러 안에서 동기로 돌아 이벤트 루프 전체가 막혔다.)
_inference_lock = asyncio.Lock()
# 클라이언트가 끊긴 전사를 확인하는 주기(초)
_DISCONNECT_POLL_SECONDS = 0.5


class TranscriptionCancelled(Exception):
    """클라이언트가 연결을 끊어 전사를 중단했다 (타임아웃·취소)."""


class ModelNotInstalled(Exception):
    """models-dir 에도 HF 캐시에도 없는 모델 — 암묵적으로 내려받지 않는다."""

# ── 다운로드 상태 (스레드 공유) ────────────────────────────

_download_lock = threading.Lock()
_download_thread: threading.Thread | None = None
_download_cancel = threading.Event()
_download_state: dict = {
    "status": "idle",  # idle | downloading | done | cancelled | error
    "model_id": None,
    "percent": 0,
    "downloaded_bytes": 0,
    "total_bytes": 0,
    "bytes_per_second": 0,
    "message": None,
}

# faster-whisper가 다운로드하는 파일과 동일한 화이트리스트
_DOWNLOAD_PATTERNS = [
    "config.json",
    "preprocessor_config.json",
    "model.bin",
    "tokenizer.json",
    "vocabulary.*",
]

# faster_whisper.utils._MODELS 매핑 실패 시 폴백
_FALLBACK_REPOS = {
    "large-v3-turbo": "mobiuslabsgmbh/faster-whisper-large-v3-turbo",
    "turbo": "mobiuslabsgmbh/faster-whisper-large-v3-turbo",
}

# ── FastAPI 앱 ─────────────────────────────────────────────


@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
    """서버 시작/종료 생명주기."""
    logger.info("Sidecar 서버 시작")
    _detect_gpu()
    yield
    logger.info("Sidecar 서버 종료")


app = FastAPI(title="D3RO-VOICE STT Sidecar", lifespan=lifespan)


def _detect_gpu() -> None:
    """GPU(CUDA) 사용 가능 여부를 ctranslate2로 감지한다.

    torch 의존 제거를 위해 ctranslate2의 네이티브 CUDA 감지를 사용한다.
    ctranslate2는 faster-whisper의 백엔드이므로 항상 함께 설치된다.
    """
    global _gpu_available, _gpu_choice
    try:
        import ctranslate2

        cuda_count = ctranslate2.get_cuda_device_count()
        supported: set[str] = set()
        if cuda_count > 0:
            try:
                supported = set(ctranslate2.get_supported_compute_types("cuda"))
            except Exception as exc:
                logger.info("CUDA compute type 조회 실패: %s", exc)
        _gpu_choice = choose_gpu_device(cuda_count, supported)
        _gpu_available = _gpu_choice is not None
        if _gpu_choice is not None:
            logger.info(
                "GPU 감지: CUDA 디바이스 %d개 (compute=%s)",
                cuda_count,
                _gpu_choice.compute_type,
            )
        elif cuda_count > 0:
            logger.info("CUDA 디바이스는 있으나 지원 compute type 없음, CPU 모드로 동작")
        else:
            logger.info("GPU 미감지, CPU 모드로 동작")
    except Exception as exc:
        _gpu_available = False
        _gpu_choice = None
        logger.info("GPU 감지 실패, CPU 모드로 동작: %s", exc)


def _disable_gpu(reason: BaseException) -> None:
    """GPU 경로가 실제로 동작하지 않음이 확인되면 이후 모델은 모두 CPU 로 올린다."""
    global _gpu_available, _gpu_choice
    if _gpu_available:
        logger.warning("GPU 사용 불가 → CPU(int8) 모드로 전환: %s", reason)
    _gpu_available = False
    _gpu_choice = None


def _cpu_threads() -> int:
    """CPU 추론에 사용할 스레드 수 (과도한 점유 방지 위해 8로 상한)."""
    return max(1, min(8, os.cpu_count() or 4))


# ── 모델 다운로드 헬퍼 ─────────────────────────────────────


def _resolve_repo(model_id: str) -> str:
    """모델 ID를 HuggingFace repo ID로 변환한다."""
    if "/" in model_id:
        return model_id
    try:
        from faster_whisper.utils import _MODELS

        if model_id in _MODELS:
            return _MODELS[model_id]
    except Exception:
        pass
    if model_id in _FALLBACK_REPOS:
        return _FALLBACK_REPOS[model_id]
    return f"Systran/faster-whisper-{model_id}"


def _local_model_dir(model_id: str) -> Path | None:
    """models_dir 내 다운로드 완료된 모델 디렉토리를 반환한다 (없으면 None)."""
    if _models_dir is None:
        return None
    model_dir = _models_dir / model_id
    if (model_dir / "model.bin").exists():
        return model_dir
    return None


def _set_download_state(**kwargs: object) -> None:
    with _download_lock:
        _download_state.update(kwargs)


def _download_worker(model_id: str) -> None:
    """백그라운드 스레드: HF repo 파일들을 스트리밍 다운로드한다."""
    import requests
    from huggingface_hub import HfApi, hf_hub_url

    try:
        repo_id = _resolve_repo(model_id)
        logger.info("모델 다운로드 시작: %s (repo=%s)", model_id, repo_id)

        api = HfApi()
        info = api.model_info(repo_id, files_metadata=True)
        files = [
            s
            for s in (info.siblings or [])
            if any(fnmatch.fnmatch(s.rfilename, p) for p in _DOWNLOAD_PATTERNS)
        ]
        if not files:
            raise RuntimeError(f"다운로드할 파일이 없습니다: {repo_id}")

        assert _models_dir is not None
        target_dir = _models_dir / model_id
        target_dir.mkdir(parents=True, exist_ok=True)

        total_bytes = sum(s.size or 0 for s in files)
        downloaded = 0
        start_time = time.monotonic()
        _set_download_state(total_bytes=total_bytes, downloaded_bytes=0, percent=0)

        for sibling in files:
            fname = sibling.rfilename
            fsize = sibling.size or 0
            dest = target_dir / fname

            # 멱등: 이미 크기 일치하는 파일은 스킵
            if dest.exists() and fsize > 0 and dest.stat().st_size == fsize:
                downloaded += fsize
                _set_download_state(
                    downloaded_bytes=downloaded,
                    percent=int(downloaded * 100 / total_bytes) if total_bytes else 0,
                )
                logger.info("이미 존재, 스킵: %s", fname)
                continue

            if _download_cancel.is_set():
                raise InterruptedError()

            url = hf_hub_url(repo_id, fname)
            part = dest.with_suffix(dest.suffix + ".part")
            logger.info("다운로드: %s (%.1f MB)", fname, fsize / 1e6)

            with requests.get(url, stream=True, timeout=30) as resp:
                resp.raise_for_status()
                with open(part, "wb") as fh:
                    for chunk in resp.iter_content(chunk_size=1024 * 1024):
                        if _download_cancel.is_set():
                            raise InterruptedError()
                        fh.write(chunk)
                        downloaded += len(chunk)
                        elapsed = time.monotonic() - start_time
                        _set_download_state(
                            downloaded_bytes=downloaded,
                            percent=(
                                int(downloaded * 100 / total_bytes) if total_bytes else 0
                            ),
                            bytes_per_second=int(downloaded / elapsed) if elapsed > 0 else 0,
                        )
            os.replace(part, dest)

        _set_download_state(status="done", percent=100)
        logger.info("모델 다운로드 완료: %s (%.1f MB)", model_id, downloaded / 1e6)

    except InterruptedError:
        _set_download_state(status="cancelled", message="사용자 취소")
        logger.info("모델 다운로드 취소: %s", model_id)
        _cleanup_partial(model_id)
    except Exception as exc:
        _set_download_state(status="error", message=str(exc))
        logger.error("모델 다운로드 실패: %s", exc, exc_info=True)
        _cleanup_partial(model_id)


def _cleanup_partial(model_id: str) -> None:
    """취소/실패 시 .part 잔여 파일 정리."""
    if _models_dir is None:
        return
    target_dir = _models_dir / model_id
    if not target_dir.exists():
        return
    for part in target_dir.glob("*.part"):
        try:
            part.unlink()
        except OSError:
            pass


def _build_transcribe_kwargs(
    language: str,
    vad_filter: str,
    initial_prompt: str,
    is_partial: bool,
) -> dict:
    """전사 옵션을 만든다.

    받아쓰기 정합성을 위해 컨텍스트 누적(condition_on_previous_text)을 끈다.
    Whisper가 앞 세그먼트 오류를 반복 증폭하는 현상(환각 루프)을 막는다.
    미리보기(partial)는 지연이 목표이므로 greedy + VAD 없음으로 디코딩한다.
    """
    if is_partial:
        kwargs: dict = {
            "beam_size": 1,
            "temperature": 0.0,
            "vad_filter": False,
            "condition_on_previous_text": False,
            "word_timestamps": False,
        }
    else:
        kwargs = {
            "beam_size": 5,
            # 0.0 단일 온도는 실패 시 재시도가 없어 환각이 남는다.
            # 낮은 온도 폴백만 허용하되 컨텍스트를 끊어 반복을 차단한다.
            "temperature": [0.0, 0.2, 0.4],
            "condition_on_previous_text": False,
            "no_speech_threshold": 0.6,
            "compression_ratio_threshold": 2.4,
            "log_prob_threshold": -1.0,
            "vad_filter": vad_filter.lower() == "true",
            "word_timestamps": False,
        }
        if kwargs["vad_filter"]:
            # 무음 구간을 촘촘히 잘라 속도를 올린다.
            kwargs["vad_parameters"] = {"min_silence_duration_ms": 300}

    if language != "auto":
        kwargs["language"] = language

    if initial_prompt and not is_partial:
        kwargs["initial_prompt"] = initial_prompt

    return kwargs


def _run_transcription(
    model: "WhisperModel",
    audio_array: np.ndarray,
    transcribe_kwargs: dict,
    cancel: threading.Event | None = None,
) -> tuple[list[dict], str, str]:
    """모델로 전사하고 세그먼트를 끝까지 소비한다.

    faster-whisper 는 세그먼트를 지연 생성하므로 디코더 오류(GPU 런타임 포함)는
    반복 중에 난다. 호출부가 전체를 한 단위로 재시도할 수 있도록 여기서 모두 소비한다.
    Returns: (segments, full_text, detected_language)
    """
    # VAD가 전체 오디오를 제거하면 max() 에러 발생 → VAD 없이 재시도
    try:
        segments_iter, info = model.transcribe(audio_array, **transcribe_kwargs)
    except ValueError as ve:
        if "empty sequence" in str(ve) and transcribe_kwargs.get("vad_filter"):
            logger.warning("VAD가 전체 오디오를 제거함 → VAD 없이 재시도")
            transcribe_kwargs["vad_filter"] = False
            segments_iter, info = model.transcribe(audio_array, **transcribe_kwargs)
        else:
            raise

    segments_list: list[dict] = []
    full_text_parts: list[str] = []

    for segment in segments_iter:
        # 클라이언트가 떠났으면(타임아웃·취소) 남은 디코딩을 버린다 — 끝까지 돌면 다음 받아쓰기가 막힌다.
        if cancel is not None and cancel.is_set():
            raise TranscriptionCancelled("client disconnected")
        seg_dict = {
            "text": segment.text.strip(),
            "start": round(segment.start, 3),
            "end": round(segment.end, 3),
            "avg_logprob": round(segment.avg_logprob, 4),
        }
        segments_list.append(seg_dict)
        full_text_parts.append(segment.text.strip())

    full_text = " ".join(full_text_parts).strip()
    detected_language = info.language if info.language else "unknown"
    return segments_list, full_text, detected_language


# ── 엔드포인트 ─────────────────────────────────────────────


@app.get("/health")
async def health() -> JSONResponse:
    """헬스체크. sidecar가 준비되었는지 확인한다."""
    return JSONResponse(
        content={
            "status": "ready" if _model is not None else "no_model",
            "model": _model_id,
            "model_loaded": _model is not None,
            "aux_models": list(_aux_models.keys()),
            "gpu": _gpu_available,
            "device": "cuda" if _gpu_available else "cpu",
        }
    )


def _create_model(model_id: str, choice: DeviceChoice) -> "WhisperModel":
    """모델을 올린다. /download 로 받아 둔 로컬 디렉토리가 있으면 그것을 쓴다."""
    from faster_whisper import WhisperModel

    local_dir = _local_model_dir(model_id)
    model_source = str(local_dir) if local_dir else model_id
    if local_dir:
        logger.info("로컬 모델 디렉토리 사용: %s", local_dir)
    logger.info(
        "모델 생성: %s (device=%s, compute=%s)", model_id, choice.device, choice.compute_type
    )
    return WhisperModel(
        model_source,
        device=choice.device,
        compute_type=choice.compute_type,
        cpu_threads=_cpu_threads(),
        num_workers=1,
    )


# 0.5초 @16kHz 무음. GPU 모델이 cuBLAS 등을 실제로 로드할 수 있는지 확인하는 데 쓴다.
_PROBE_SAMPLES = 8000


def _probe_model(model: "WhisperModel") -> None:
    """짧은 무음 전사로 인코더·디코더를 한 번 돌려 본다 (실패 시 예외)."""
    silence = np.zeros(_PROBE_SAMPLES, dtype=np.float32)
    segments, _info = model.transcribe(
        silence,
        language="en",
        beam_size=1,
        temperature=0.0,
        vad_filter=False,
        condition_on_previous_text=False,
        without_timestamps=True,
    )
    # faster-whisper 는 세그먼트를 지연 생성하므로 끝까지 소비해야 디코더가 돈다.
    for _ in segments:
        pass


def _load_on_best_device(model_id: str) -> "WhisperModel":
    """GPU 후보가 있으면 GPU 로 올려 검증하고, 안 되면 CPU(int8)로 올린다."""

    def on_fallback(failed: DeviceChoice, exc: BaseException) -> None:
        logger.warning(
            "GPU 모델 검증 실패 (%s, compute=%s) → CPU 로 재로딩: %s",
            model_id,
            failed.compute_type,
            exc,
        )
        _disable_gpu(exc)

    preferred = _gpu_choice if _gpu_available else None
    model, choice = load_with_fallback(
        build=lambda c: _create_model(model_id, c),
        verify=_probe_model,
        preferred=preferred,
        on_fallback=on_fallback,
    )
    _model_devices[model_id] = choice
    return model


def _reload_on_cpu(model_id: str, is_primary: bool) -> "WhisperModel":
    """전사 중 GPU 런타임 오류가 난 모델을 CPU 로 다시 올려 같은 자리에 둔다."""
    global _model
    if is_primary:
        _model = None
    else:
        _aux_models.pop(model_id, None)
    model = _create_model(model_id, CPU_CHOICE)
    _model_devices[model_id] = CPU_CHOICE
    if is_primary:
        _model = model
    else:
        _aux_models[model_id] = model
    return model


def _ensure_model_available(model_id: str) -> None:
    """models-dir 을 쓰는 설치본에서, 받지 않은 모델을 /load 가 HF 에서 몰래 내려받지 않게 한다.

    models-dir 에 있거나 HF 캐시에 이미 있으면 통과한다. models-dir 을 지정하지 않은 실행(개발·테스트)은
    예전처럼 faster-whisper 에 맡긴다(HF 캐시만 사용).
    """
    if _models_dir is None or _local_model_dir(model_id) is not None:
        return
    try:
        from faster_whisper.utils import download_model

        download_model(model_id, local_files_only=True)
    except Exception as exc:  # noqa: BLE001 — 캐시에 없으면 여러 종류의 예외가 난다
        raise ModelNotInstalled(f"모델이 설치되어 있지 않습니다: {model_id}") from exc


@app.post("/load")
async def load_model(body: dict) -> JSONResponse:  # noqa: ANN001
    """Whisper 모델을 로딩한다.

    Request body:
        { "model_id": "large-v3" }  -- tiny, base, small, medium, large-v3

    Returns:
        { "status": "loaded", "model_id": "large-v3", "load_time_ms": 1234 }
    """
    global _model, _model_id

    model_id: str = body.get("model_id", "large-v3-turbo")
    # primary = 받아쓰기(기본) 모델, aux = 실시간 자막처럼 따로 고른 보조 모델.
    slot: str = body.get("slot", "primary")
    logger.info("모델 로딩 시작: %s (slot=%s)", model_id, slot)

    start_time = time.monotonic()

    # 같은 모델이 이미 로딩되어 있으면 재사용 (재로딩은 수초 지연을 만든다)
    if (_model is not None and _model_id == model_id) or (slot == "aux" and model_id in _aux_models):
        logger.info("이미 로딩된 모델 재사용: %s", model_id)
        return JSONResponse(
            content={
                "status": "loaded",
                "model_id": model_id,
                "load_time_ms": 0,
                "reused": True,
            }
        )

    try:
        # 설치하지 않은 모델은 올리지 않는다 — 쓰던 모델을 내리기 전에 확인한다.
        await asyncio.to_thread(_ensure_model_available, model_id)
    except ModelNotInstalled as exc:
        logger.warning("모델 로딩 거부 (미설치): %s", exc)
        return JSONResponse(
            status_code=404,
            content={"status": "error", "code": "model_not_installed", "message": str(exc)},
        )

    try:
        async with _inference_lock:
            if slot == "aux":
                # 보조 자리는 하나만 둔다 — 다른 보조 모델은 내려 VRAM 을 돌려받는다.
                _aux_models.clear()
                _aux_models[model_id] = await asyncio.to_thread(_load_on_best_device, model_id)
            else:
                # 모델 교체 시 이전 모델을 먼저 해제해 VRAM/RAM을 회수한다.
                _model = None
                _model = await asyncio.to_thread(_load_on_best_device, model_id)
                _model_id = model_id
                # 기본 모델이 된 모델은 보조 자리에 중복으로 들고 있지 않는다.
                _aux_models.pop(model_id, None)

        load_time_ms = int((time.monotonic() - start_time) * 1000)
        logger.info("모델 로딩 완료: %s (slot=%s, %dms)", model_id, slot, load_time_ms)

        return JSONResponse(
            content={
                "status": "loaded",
                "model_id": model_id,
                "load_time_ms": load_time_ms,
            }
        )

    except Exception as exc:
        logger.error("모델 로딩 실패: %s", exc)
        return JSONResponse(
            status_code=500,
            content={"status": "error", "message": str(exc)},
        )


async def _watch_disconnect(request: Request, cancel: threading.Event) -> None:
    """클라이언트가 연결을 끊으면(타임아웃 abort 등) cancel 을 세운다."""
    while not cancel.is_set():
        if await request.is_disconnected():
            cancel.set()
            return
        await asyncio.sleep(_DISCONNECT_POLL_SECONDS)


def _transcribe_blocking(
    model: "WhisperModel",
    audio_array: np.ndarray,
    transcribe_kwargs: dict,
    resolved_model_id: str | None,
    is_primary: bool,
    cancel: threading.Event,
) -> tuple[list[dict], str, str]:
    """워커 스레드에서 전사한다 (GPU 런타임 오류면 CPU 로 다시 올려 한 번만 재시도)."""
    try:
        return _run_transcription(model, audio_array, dict(transcribe_kwargs), cancel)
    except TranscriptionCancelled:
        raise
    except Exception as exc:
        # cuBLAS 미설치 PC 등: 검증을 통과했더라도 실제 전사에서 GPU 런타임 오류가
        # 나면 이 모델을 CPU 로 다시 올려 한 번만 재시도한다.
        device = _model_devices.get(resolved_model_id or "")
        if not (
            resolved_model_id
            and device is not None
            and device.is_gpu
            and is_gpu_runtime_error(exc)
        ):
            raise
        logger.warning(
            "전사 중 GPU 런타임 오류 → CPU 로 재로딩 후 재시도 (%s): %s",
            resolved_model_id,
            exc,
        )
        _disable_gpu(exc)
        cpu_model = _reload_on_cpu(resolved_model_id, is_primary)
        return _run_transcription(cpu_model, audio_array, dict(transcribe_kwargs), cancel)


@app.post("/transcribe")
async def transcribe(
    request: Request,
    audio: UploadFile = File(...),
    language: str = Form("auto"),
    vad_filter: str = Form("true"),
    initial_prompt: str = Form(""),
    partial: str = Form("false"),
    model_id: str = Form(""),
) -> JSONResponse:
    """오디오 파일을 전사한다.

    Multipart form:
        audio          - PCM16 16kHz mono 바이너리 파일
        language       - 언어 코드 ('auto', 'ko', 'en', ...)
        vad_filter     - VAD 필터 활성화 ('true' / 'false')
        initial_prompt - 초기 프롬프트 (컨텍스트 힌트)
        partial        - 녹음 중 미리보기 모드 ('true'면 greedy 디코딩 + 컨텍스트 미사용)
        model_id       - 쓸 모델 (비우면 기본 모델). 올라가 있지 않으면 409
    """
    is_primary = not (model_id and model_id != _model_id)
    if not is_primary:
        model = _aux_models.get(model_id)
        if model is None:
            return JSONResponse(
                status_code=409,
                content={"status": "error", "code": "model_not_loaded", "message": f"모델이 로딩되지 않았습니다: {model_id}"},
            )
    else:
        model = _model
    resolved_model_id = model_id if not is_primary else _model_id
    if model is None:
        return JSONResponse(
            status_code=503,
            content={"status": "error", "message": "모델이 로딩되지 않았습니다"},
        )

    is_partial = partial.lower() == "true"
    start_time = time.monotonic()

    try:
        pcm_bytes = await audio.read()

        if len(pcm_bytes) == 0:
            return JSONResponse(
                status_code=400,
                content={"status": "error", "message": "오디오 데이터가 비어있습니다"},
            )

        audio_array = (
            np.frombuffer(pcm_bytes, dtype=np.int16).astype(np.float32) / 32768.0
        )

        sample_rate = 16000
        audio_duration = len(audio_array) / sample_rate

        logger.info(
            "전사 시작: %.1f초 오디오, language=%s, vad=%s, partial=%s",
            audio_duration,
            language,
            vad_filter,
            is_partial,
        )

        transcribe_kwargs = _build_transcribe_kwargs(
            language=language,
            vad_filter=vad_filter,
            initial_prompt=initial_prompt,
            is_partial=is_partial,
        )

        cancel = threading.Event()
        watcher = asyncio.create_task(_watch_disconnect(request, cancel))
        try:
            async with _inference_lock:
                if cancel.is_set():
                    raise TranscriptionCancelled("client disconnected while queued")
                segments_list, full_text, detected_language = await asyncio.to_thread(
                    _transcribe_blocking,
                    model,
                    audio_array,
                    transcribe_kwargs,
                    resolved_model_id,
                    is_primary,
                    cancel,
                )
        finally:
            cancel.set()
            watcher.cancel()

        processing_time = int((time.monotonic() - start_time) * 1000)

        logger.info(
            "전사 완료: '%s' (lang=%s, %.1f초, %dms)",
            full_text[:80],
            detected_language,
            audio_duration,
            processing_time,
        )

        return JSONResponse(
            content={
                "text": full_text,
                "segments": segments_list,
                "language": detected_language,
                "duration": round(audio_duration, 3),
                "processing_time": processing_time,
            }
        )

    except TranscriptionCancelled as exc:
        logger.info("전사 중단: %s", exc)
        return JSONResponse(
            status_code=499,
            content={"status": "error", "code": "cancelled", "message": str(exc)},
        )
    except Exception as exc:
        logger.error("전사 실패: %s", exc, exc_info=True)
        return JSONResponse(
            status_code=500,
            content={"status": "error", "message": str(exc)},
        )


@app.post("/download")
async def download_model(body: dict) -> JSONResponse:  # noqa: ANN001
    """모델 다운로드를 백그라운드로 시작한다.

    Request body:
        { "model_id": "large-v3-turbo" }

    Returns:
        { "status": "started" } 또는 이미 완료된 경우 { "status": "done" }
    """
    global _download_thread

    if _models_dir is None:
        return JSONResponse(
            status_code=500,
            content={"status": "error", "message": "models-dir가 설정되지 않았습니다"},
        )

    model_id: str = body.get("model_id", "large-v3-turbo")

    # 이미 다운로드 완료된 모델이면 즉시 done
    if _local_model_dir(model_id) is not None:
        _set_download_state(status="done", model_id=model_id, percent=100)
        return JSONResponse(content={"status": "done"})

    if _download_thread is not None and _download_thread.is_alive():
        return JSONResponse(
            status_code=409,
            content={"status": "error", "message": "이미 다운로드가 진행 중입니다"},
        )

    _download_cancel.clear()
    _set_download_state(
        status="downloading",
        model_id=model_id,
        percent=0,
        downloaded_bytes=0,
        total_bytes=0,
        bytes_per_second=0,
        message=None,
    )
    _download_thread = threading.Thread(
        target=_download_worker, args=(model_id,), daemon=True
    )
    _download_thread.start()

    return JSONResponse(content={"status": "started"})


@app.get("/download/status")
async def download_status() -> JSONResponse:
    """현재 다운로드 상태를 반환한다."""
    with _download_lock:
        return JSONResponse(content=dict(_download_state))


@app.post("/download/cancel")
async def download_cancel() -> JSONResponse:
    """진행 중인 다운로드를 취소한다."""
    if _download_thread is not None and _download_thread.is_alive():
        _download_cancel.set()
        return JSONResponse(content={"status": "cancelling"})
    return JSONResponse(content={"status": "idle"})


@app.get("/uia/focus")
async def uia_focus(timeoutMs: int = 1500) -> JSONResponse:
    """포커스된 입력 요소의 UIA 스냅샷 (텍스트/케어렛/비밀번호 여부).

    제안(ghost text)과 이핑 학습이 쓰는 유일한 입력창 읽기 경로다.
    비밀번호 필드는 브리지 안에서 fail-closed 로 차단한다.
    """
    try:
        import uia_bridge
    except Exception as exc:  # pragma: no cover - 파일 누락 등
        return JSONResponse(content={"available": False, "reason": f"bridge-import:{exc}"})

    snapshot = await asyncio.to_thread(uia_bridge.snapshot_focus, timeoutMs)
    return JSONResponse(content=snapshot)


@app.post("/shutdown")
async def shutdown() -> JSONResponse:
    """서버를 graceful하게 종료한다."""
    logger.info("종료 요청 수신")

    try:
        import uia_bridge

        await asyncio.to_thread(uia_bridge.shutdown)
    except Exception:
        pass

    if _server is not None:
        _server.should_exit = True

    return JSONResponse(content={"status": "shutting_down"})


# ── 메인 ───────────────────────────────────────────────────


def main() -> None:
    """CLI 진입점."""
    global _server, _models_dir

    parser = argparse.ArgumentParser(description="D3RO-VOICE STT Sidecar")
    parser.add_argument(
        "--port",
        type=int,
        default=18765,
        help="HTTP 서버 포트 (기본: 18765)",
    )
    parser.add_argument(
        "--host",
        type=str,
        default="127.0.0.1",
        help="HTTP 서버 호스트 (기본: 127.0.0.1)",
    )
    parser.add_argument(
        "--models-dir",
        type=str,
        default=None,
        help="사전 다운로드 모델 저장 디렉토리 (미지정 시 HF 캐시만 사용)",
    )
    args = parser.parse_args()

    if args.models_dir:
        _models_dir = Path(args.models_dir)
        _models_dir.mkdir(parents=True, exist_ok=True)

    logger.info("D3RO-VOICE STT Sidecar 시작 (port=%d)", args.port)

    def signal_handler(signum: int, _frame: object) -> None:
        sig_name = signal.Signals(signum).name
        logger.info("시그널 수신: %s, 종료 시작", sig_name)
        if _server is not None:
            _server.should_exit = True

    signal.signal(signal.SIGINT, signal_handler)
    signal.signal(signal.SIGTERM, signal_handler)

    config = uvicorn.Config(
        app=app,
        host=args.host,
        port=args.port,
        log_level="warning",
        access_log=False,
    )
    _server = uvicorn.Server(config)
    _server.run()

    logger.info("Sidecar 서버 종료 완료")


if __name__ == "__main__":
    main()