@hypit/hypit 0.0.1 → 0.1.0

package/services/whisperx/src/hypit_whisperx_service/application.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Mapping, Protocol
+
+from . import PROTOCOL, SERVICE_VERSION
+from .audio import AudioInputError, CanonicalAudio, read_canonical_audio
+from .config import ServiceConfig
+from .engine import InferenceBusyError, InferenceInputError, normalize_language
+
+
+class AlignmentEngine(Protocol):
+    def identity(self) -> dict[str, object]: ...
+
+    def transcribe(self, audio: CanonicalAudio, language: str | None) -> dict[str, object]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationResponse:
+    status: int
+    body: bytes
+
+
+class RequestError(ValueError):
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+def _json_response(status: int, value: object) -> ApplicationResponse:
+    return ApplicationResponse(
+        status=status,
+        body=json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8"),
+    )
+
+
+class WhisperXApplication:
+    def __init__(self, config: ServiceConfig, engine: AlignmentEngine):
+        self.config = config
+        self.engine = engine
+
+    def health(self) -> ApplicationResponse:
+        return _json_response(200, {
+            "ok": True,
+            "protocol": PROTOCOL,
+            "serviceVersion": SERVICE_VERSION,
+            **self.engine.identity(),
+        })
+
+    def transcribe(self, headers: Mapping[str, str], body: bytes) -> ApplicationResponse:
+        content_type = headers.get("content-type", "").split(";", 1)[0].strip().lower()
+        if content_type != "application/json":
+            raise RequestError(415, "UNSUPPORTED_MEDIA_TYPE", "Content-Type must be application/json")
+        if len(body) > self.config.max_request_bytes:
+            raise RequestError(413, "REQUEST_TOO_LARGE", "request body exceeds the configured limit")
+        try:
+            request = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise RequestError(400, "INVALID_JSON", "request body is not valid UTF-8 JSON") from error
+        if not isinstance(request, dict):
+            raise RequestError(400, "INVALID_REQUEST", "request body must be an object")
+        unknown = set(request) - {"audio_path", "language"}
+        if unknown:
+            raise RequestError(400, "UNKNOWN_FIELD", f"unknown request field: {sorted(unknown)[0]}")
+        audio_path = request.get("audio_path")
+        if not isinstance(audio_path, str) or not audio_path:
+            raise RequestError(400, "INVALID_AUDIO_PATH", "audio_path must be a non-empty string")
+        try:
+            language = normalize_language(request.get("language"))
+            audio = read_canonical_audio(
+                audio_path,
+                self.config.input_roots,
+                self.config.max_audio_bytes,
+            )
+        except (AudioInputError, ValueError) as error:
+            raise RequestError(400, "INVALID_INPUT", str(error)) from error
+        try:
+            result = self.engine.transcribe(audio, language)
+        except InferenceInputError as error:
+            raise RequestError(400, "INVALID_INPUT", str(error)) from error
+        except InferenceBusyError as error:
+            raise RequestError(503, "BUSY", str(error)) from error
+        return _json_response(200, result)
+
+    def error(self, error: RequestError) -> ApplicationResponse:
+        return _json_response(error.status, {"error": {"code": error.code, "message": str(error)}})

package/services/whisperx/src/hypit_whisperx_service/audio.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import wave
+
+
+SAMPLE_RATE = 16_000
+
+
+class AudioInputError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalAudio:
+    path: Path
+    sample_frames: int
+    pcm_s16le: bytes
+
+    @property
+    def duration_sec(self) -> float:
+        return self.sample_frames / SAMPLE_RATE
+
+
+def _inside(path: Path, roots: tuple[Path, ...]) -> bool:
+    return any(path == root or path.is_relative_to(root) for root in roots)
+
+
+def read_canonical_audio(
+    raw_path: str,
+    roots: tuple[Path, ...],
+    max_audio_bytes: int,
+) -> CanonicalAudio:
+    requested = Path(raw_path).expanduser()
+    if not requested.is_absolute():
+        raise AudioInputError("audio_path must be absolute")
+    try:
+        path = requested.resolve(strict=True)
+    except OSError as error:
+        raise AudioInputError("audio_path does not identify a readable file") from error
+    if not _inside(path, roots):
+        raise AudioInputError("audio_path is outside HYPIT_WHISPERX_INPUT_ROOTS")
+    if not path.is_file():
+        raise AudioInputError("audio_path must identify a regular file")
+    if path.stat().st_size > max_audio_bytes:
+        raise AudioInputError("audio input exceeds HYPIT_WHISPERX_MAX_AUDIO_BYTES")
+
+    try:
+        with wave.open(str(path), "rb") as source:
+            channels = source.getnchannels()
+            sample_width = source.getsampwidth()
+            sample_rate = source.getframerate()
+            sample_frames = source.getnframes()
+            compression = source.getcomptype()
+            payload = source.readframes(sample_frames + 1)
+    except (OSError, EOFError, wave.Error) as error:
+        raise AudioInputError("audio input is not a valid WAV file") from error
+
+    if compression != "NONE" or channels != 1 or sample_width != 2 or sample_rate != SAMPLE_RATE:
+        raise AudioInputError("audio input must be 16 kHz mono PCM s16 WAV")
+    if sample_frames <= 0:
+        raise AudioInputError("audio input must contain at least one sample frame")
+    if len(payload) != sample_frames * 2:
+        raise AudioInputError("WAV data length differs from its declared sample count")
+    return CanonicalAudio(path=path, sample_frames=sample_frames, pcm_s16le=payload)

package/services/whisperx/src/hypit_whisperx_service/check.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import importlib.metadata as metadata
+import json
+import sys
+
+from . import PROTOCOL, SERVICE_VERSION
+from .config import ServiceConfig
+from .resources import assert_punkt_tab
+
+
+def main() -> None:
+    if not ((3, 10) <= sys.version_info[:2] < (3, 14)):
+        raise RuntimeError(f"WhisperX service requires Python >=3.10,<3.14; got {sys.version.split()[0]}")
+    config = ServiceConfig.from_environment()
+    assert_punkt_tab(config.nltk_data_root)
+    import numpy  # noqa: F401
+    import whisperx
+
+    for name in ("load_model", "load_align_model", "align"):
+        if not callable(getattr(whisperx, name, None)):
+            raise RuntimeError(f"installed WhisperX is missing required API: {name}")
+    versions = {
+        name: metadata.version(name)
+        for name in ("hypit-whisperx-service", "whisperx", "faster-whisper", "numpy", "torch")
+    }
+    if versions["whisperx"] != "3.8.6":
+        raise RuntimeError(f"expected whisperx 3.8.6, got {versions['whisperx']}")
+    print(json.dumps({
+        "ok": True,
+        "protocol": PROTOCOL,
+        "serviceVersion": SERVICE_VERSION,
+        "python": sys.version.split()[0],
+        "packages": versions,
+    }, sort_keys=True))

package/services/whisperx/src/hypit_whisperx_service/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import tempfile
+from typing import Mapping
+
+from .resources import default_nltk_data_root
+
+
+def _positive_integer(value: str, name: str, maximum: int | None = None) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as error:
+        raise ValueError(f"{name} must be an integer") from error
+    if parsed <= 0 or (maximum is not None and parsed > maximum):
+        suffix = f" no greater than {maximum}" if maximum is not None else ""
+        raise ValueError(f"{name} must be positive{suffix}")
+    return parsed
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceConfig:
+    port: int
+    model: str
+    device: str
+    compute: str
+    batch_size: int
+    input_roots: tuple[Path, ...]
+    nltk_data_root: Path
+    max_request_bytes: int
+    max_audio_bytes: int
+
+    @classmethod
+    def from_environment(cls, environment: Mapping[str, str] | None = None) -> "ServiceConfig":
+        env = os.environ if environment is None else environment
+        device = env.get("HYPIT_WHISPERX_DEVICE", "cpu").strip()
+        model = env.get("HYPIT_WHISPERX_MODEL", "small").strip()
+        compute = env.get(
+            "HYPIT_WHISPERX_COMPUTE",
+            "int8" if device == "cpu" else "float16",
+        ).strip()
+        if not model:
+            raise ValueError("HYPIT_WHISPERX_MODEL must not be empty")
+        if not device:
+            raise ValueError("HYPIT_WHISPERX_DEVICE must not be empty")
+        if not compute:
+            raise ValueError("HYPIT_WHISPERX_COMPUTE must not be empty")
+
+        raw_roots = env.get("HYPIT_WHISPERX_INPUT_ROOTS", tempfile.gettempdir())
+        roots = tuple(
+            Path(item).expanduser().resolve()
+            for item in raw_roots.split(os.pathsep)
+            if item.strip()
+        )
+        if not roots:
+            raise ValueError("HYPIT_WHISPERX_INPUT_ROOTS must contain at least one path")
+
+        return cls(
+            port=_positive_integer(env.get("HYPIT_WHISPERX_PORT", "8765"), "HYPIT_WHISPERX_PORT", 65535),
+            model=model,
+            device=device,
+            compute=compute,
+            batch_size=_positive_integer(
+                env.get("HYPIT_WHISPERX_BATCH_SIZE", "8"),
+                "HYPIT_WHISPERX_BATCH_SIZE",
+            ),
+            input_roots=roots,
+            nltk_data_root=Path(
+                env.get("HYPIT_WHISPERX_NLTK_DATA", str(default_nltk_data_root()))
+            ).expanduser().resolve(),
+            max_request_bytes=_positive_integer(
+                env.get("HYPIT_WHISPERX_MAX_REQUEST_BYTES", str(64 * 1024)),
+                "HYPIT_WHISPERX_MAX_REQUEST_BYTES",
+            ),
+            max_audio_bytes=_positive_integer(
+                env.get("HYPIT_WHISPERX_MAX_AUDIO_BYTES", str(512 * 1024 * 1024)),
+                "HYPIT_WHISPERX_MAX_AUDIO_BYTES",
+            ),
+        )

package/services/whisperx/src/hypit_whisperx_service/engine.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import importlib.metadata as metadata
+import math
+import os
+import threading
+from typing import Any, Mapping
+
+from .audio import CanonicalAudio
+from .config import ServiceConfig
+from .resources import assert_punkt_tab
+
+
+class InferenceInputError(ValueError):
+    pass
+
+
+class InferenceBusyError(RuntimeError):
+    pass
+
+
+def normalize_language(value: object) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError("language must be a string")
+    language = value.strip().lower()
+    if not language or language in {"auto", "detect", "und", "unknown"}:
+        return None
+    if len(language) > 32 or not all(character.isalnum() or character in {"-", "_"} for character in language):
+        raise ValueError("language is invalid")
+    return language
+
+
+def _finite(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    number = float(value)
+    return number if math.isfinite(number) else None
+
+
+def normalize_alignment(language: str, raw: Mapping[str, Any]) -> dict[str, object]:
+    raw_segments = raw.get("segments", [])
+    if not isinstance(raw_segments, list):
+        raise RuntimeError("WhisperX alignment returned a non-array segments value")
+    segments: list[dict[str, object]] = []
+    for raw_segment in raw_segments:
+        if not isinstance(raw_segment, Mapping):
+            raise RuntimeError("WhisperX alignment returned an invalid segment")
+        raw_words = raw_segment.get("words", [])
+        if not isinstance(raw_words, list):
+            raise RuntimeError("WhisperX alignment returned a non-array words value")
+        words: list[dict[str, object]] = []
+        for raw_word in raw_words:
+            if not isinstance(raw_word, Mapping):
+                raise RuntimeError("WhisperX alignment returned an invalid word")
+            value = raw_word.get("word", raw_word.get("text", ""))
+            text = value.strip() if isinstance(value, str) else ""
+            if not text:
+                continue
+            start = _finite(raw_word.get("start"))
+            end = _finite(raw_word.get("end"))
+            score = _finite(raw_word.get("score"))
+            word: dict[str, object] = {"text": text}
+            # Missing or partial acoustic evidence stays missing. Never manufacture a tick.
+            if start is not None and end is not None and 0 <= start <= end:
+                word.update(start=start, end=end)
+            if score is not None and 0 <= score <= 1:
+                word["score"] = score
+            words.append(word)
+        if not words:
+            continue
+        segment_text = raw_segment.get("text")
+        segment: dict[str, object] = {
+            "text": segment_text.strip() if isinstance(segment_text, str) else " ".join(
+                str(word["text"]) for word in words
+            ),
+            "words": words,
+        }
+        start = _finite(raw_segment.get("start"))
+        end = _finite(raw_segment.get("end"))
+        if start is not None and end is not None and 0 <= start <= end:
+            segment.update(start=start, end=end)
+        segments.append(segment)
+    return {"language": language, "segments": segments}
+
+
+class WhisperXEngine:
+    def __init__(self, config: ServiceConfig):
+        assert_punkt_tab(config.nltk_data_root)
+        os.environ["NLTK_DATA"] = str(config.nltk_data_root)
+        try:
+            import numpy as numpy_module
+            import whisperx as whisperx_module
+        except ImportError as error:
+            raise RuntimeError(
+                "WhisperX runtime is unavailable; run `uv sync --project services/whisperx --frozen`"
+            ) from error
+        self._numpy = numpy_module
+        self._whisperx = whisperx_module
+        import nltk
+        if str(config.nltk_data_root) not in nltk.data.path:
+            nltk.data.path.insert(0, str(config.nltk_data_root))
+        self._config = config
+        self._inference_lock = threading.Lock()
+        self._alignment_models: dict[str, tuple[object, object]] = {}
+        self._asr = whisperx_module.load_model(
+            config.model,
+            config.device,
+            compute_type=config.compute,
+        )
+        self._whisperx_version = metadata.version("whisperx")
+
+    def identity(self) -> dict[str, object]:
+        return {
+            "model": self._config.model,
+            "device": self._config.device,
+            "compute": self._config.compute,
+            "batchSize": self._config.batch_size,
+            "whisperxVersion": self._whisperx_version,
+        }
+
+    def _alignment_model(self, language: str) -> tuple[object, object]:
+        model = self._alignment_models.get(language)
+        if model is None:
+            loaded = self._whisperx.load_align_model(
+                language_code=language,
+                device=self._config.device,
+            )
+            if not isinstance(loaded, tuple) or len(loaded) != 2:
+                raise RuntimeError("WhisperX returned an invalid alignment model")
+            model = loaded
+            self._alignment_models[language] = model
+        return model
+
+    def transcribe(self, audio: CanonicalAudio, language: str | None) -> dict[str, object]:
+        if self._config.model.endswith(".en") and language not in {None, "en"}:
+            raise InferenceInputError(
+                f"model {self._config.model!r} is English-only and cannot transcribe {language!r}"
+            )
+        samples = self._numpy.frombuffer(audio.pcm_s16le, dtype="<i2").astype(self._numpy.float32)
+        samples /= 32768.0
+        samples = self._numpy.ascontiguousarray(samples)
+        if not self._inference_lock.acquire(blocking=False):
+            raise InferenceBusyError("the warm WhisperX model is already executing one request")
+        try:
+            transcription = self._asr.transcribe(
+                samples,
+                batch_size=self._config.batch_size,
+                language=language,
+            )
+            detected = transcription.get("language") or language or "en"
+            if not isinstance(detected, str) or not detected.strip():
+                raise RuntimeError("WhisperX did not return a valid language")
+            segments = transcription.get("segments", [])
+            if not isinstance(segments, list):
+                raise RuntimeError("WhisperX transcription returned invalid segments")
+            if not segments:
+                return {"language": detected, "segments": []}
+            alignment_model, metadata_value = self._alignment_model(detected)
+            aligned = self._whisperx.align(
+                segments,
+                alignment_model,
+                metadata_value,
+                samples,
+                self._config.device,
+                return_char_alignments=False,
+            )
+            if not isinstance(aligned, Mapping):
+                raise RuntimeError("WhisperX returned an invalid alignment result")
+            return normalize_alignment(detected, aligned)
+        finally:
+            self._inference_lock.release()

package/services/whisperx/src/hypit_whisperx_service/prepare.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .resources import default_nltk_data_root, prepare_punkt_tab
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Install NLTK data required by Hypit WhisperX")
+    parser.add_argument(
+        "--nltk-data",
+        type=Path,
+        default=default_nltk_data_root(),
+        help="NLTK data root (defaults to the SVML user cache)",
+    )
+    arguments = parser.parse_args()
+    path = prepare_punkt_tab(arguments.nltk_data)
+    print(path)

package/services/whisperx/src/hypit_whisperx_service/resources.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def default_nltk_data_root() -> Path:
+    return Path.home() / ".cache" / "hypit" / "whisperx" / "nltk_data"
+
+
+def assert_punkt_tab(root: Path) -> None:
+    import nltk
+
+    location = str(root.expanduser().resolve())
+    if location not in nltk.data.path:
+        nltk.data.path.insert(0, location)
+    try:
+        nltk.data.find("tokenizers/punkt_tab", paths=[location])
+    except LookupError as error:
+        raise RuntimeError(
+            "NLTK punkt_tab data is unavailable; run `hypit-whisperx-prepare`"
+        ) from error
+
+
+def prepare_punkt_tab(root: Path) -> Path:
+    import nltk
+
+    root = root.expanduser().resolve()
+    target = root / "tokenizers" / "punkt_tab"
+    # Already installed is already done. `nltk.download` fetches its index before it looks at what is
+    # on disk, so preparing an installation that needs nothing still needed the network, and a machine
+    # without it failed at the step whose whole job is to make the machine ready offline.
+    try:
+        assert_punkt_tab(root)
+        return target
+    except RuntimeError:
+        pass
+    root.mkdir(parents=True, exist_ok=True)
+    if not nltk.download("punkt_tab", download_dir=str(root), quiet=False, raise_on_error=True):
+        raise RuntimeError("NLTK could not install punkt_tab")
+    assert_punkt_tab(root)
+    return target

package/services/whisperx/src/hypit_whisperx_service/server.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import logging
+import threading
+
+from .application import RequestError, WhisperXApplication
+
+
+LOGGER = logging.getLogger("hypit.whisperx")
+
+
+class WhisperXHttpServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address: tuple[str, int], application: WhisperXApplication):
+        super().__init__(address, WhisperXRequestHandler)
+        self.application = application
+
+
+class WhisperXRequestHandler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+    server_version = "hypit-whisperx"
+    sys_version = ""
+
+    @property
+    def application(self) -> WhisperXApplication:
+        server = self.server
+        if not isinstance(server, WhisperXHttpServer):
+            raise RuntimeError("invalid WhisperX server")
+        return server.application
+
+    def _send(self, status: int, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path != "/health":
+            self._send(404, b'{"error":{"code":"NOT_FOUND","message":"not found"}}')
+            return
+        response = self.application.health()
+        self._send(response.status, response.body)
+
+    def do_POST(self) -> None:  # noqa: N802
+        if self.path != "/transcribe":
+            self._send(404, b'{"error":{"code":"NOT_FOUND","message":"not found"}}')
+            return
+        try:
+            raw_length = self.headers.get("Content-Length")
+            if raw_length is None:
+                raise RequestError(411, "LENGTH_REQUIRED", "Content-Length is required")
+            try:
+                length = int(raw_length)
+            except ValueError as error:
+                raise RequestError(400, "INVALID_LENGTH", "Content-Length is invalid") from error
+            if length < 0:
+                raise RequestError(400, "INVALID_LENGTH", "Content-Length is invalid")
+            if length > self.application.config.max_request_bytes:
+                raise RequestError(413, "REQUEST_TOO_LARGE", "request body exceeds the configured limit")
+            body = self.rfile.read(length)
+            if len(body) != length:
+                raise RequestError(400, "TRUNCATED_REQUEST", "request body is truncated")
+            response = self.application.transcribe(
+                {key.lower(): value for key, value in self.headers.items()},
+                body,
+            )
+        except RequestError as error:
+            response = self.application.error(error)
+        except Exception:  # noqa: BLE001
+            LOGGER.exception("WhisperX inference failed")
+            response = self.application.error(RequestError(
+                500,
+                "INFERENCE_FAILED",
+                "WhisperX inference failed",
+            ))
+        self._send(response.status, response.body)
+
+    def log_message(self, format_value: str, *args: object) -> None:
+        LOGGER.info("%s - %s", self.client_address[0], format_value % args)
+
+
+def serve(application: WhisperXApplication) -> None:
+    server = WhisperXHttpServer(("127.0.0.1", application.config.port), application)
+    LOGGER.info("ready on http://127.0.0.1:%d", application.config.port)
+    try:
+        server.serve_forever(poll_interval=0.25)
+    except KeyboardInterrupt:
+        LOGGER.info("shutdown requested")
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+def stop_in_background(server: WhisperXHttpServer) -> None:
+    threading.Thread(target=server.shutdown, daemon=True).start()