Standardize async offloading behind shared executor helper

backend/app/utils/async_utils.py

@@ -0,0 +1,42 @@
+"""Async execution utilities.
+
+Provides a shared thread-backed executor abstraction and helpers for
+running blocking callables without stalling the FastAPI event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+DEFAULT_BLOCKING_EXECUTOR: ThreadPoolExecutor = ThreadPoolExecutor(
+    max_workers=16,
+    thread_name_prefix="bangui-blocking",
+)
+
+
+async def run_blocking(
+    func: Callable[P, T],
+    *args: P.args,
+    executor: ThreadPoolExecutor | None = None,
+    **kwargs: P.kwargs,
+) -> T:
+    """Run a blocking callable in the shared thread pool.
+
+    Args:
+        func: Blocking callable to execute.
+        *args: Positional arguments for the callable.
+        executor: Optional custom executor. Defaults to the shared pool.
+        **kwargs: Keyword arguments for the callable.
+
+    Returns:
+        The callable return value.
+    """
+    loop = asyncio.get_running_loop()
+    if executor is None:
+        return await asyncio.to_thread(func, *args, **kwargs)
+    return await loop.run_in_executor(executor, func, *args, **kwargs)