utils/debug.py

import os

# Timing diagnostics are opt-in: set OCR_DEBUG_TIMING=1. The PARSED line in
# main.py always prints and carries the total elapsed time, so production
# logs keep per-request visibility without the per-stage noise.
TIMING_ENABLED = os.getenv("OCR_DEBUG_TIMING", "").lower() in ("1", "true", "yes")


def timing(msg: str) -> None:
    """Print a TIMING diagnostic when OCR_DEBUG_TIMING is set.

    Uses print(flush=True) rather than the logging module — plain logger
    calls don't reliably surface in the HF Spaces log viewer.
    """
    if TIMING_ENABLED:
        print(f"TIMING {msg}", flush=True)