core.dependency_guards module
Timeout / fallback wrappers for optional external dependencies.
guard_async_dependency() runs a coroutine under an
asyncio.wait_for() timeout and returns a safe fallback value
(logging a warning) on timeout or error, while always re-raising
asyncio.CancelledError. Used to keep a slow or unavailable
dependency (RAG, web search, …) from stalling the message pipeline.
- async core.dependency_guards.guard_async_dependency(coro, timeout_seconds, fallback_value, service_name)[source]
Run a coroutine under a timeout, returning a fallback instead of failing.
Awaits coro inside
asyncio.wait_for()so a slow or unavailable optional dependency (RAG, web search, an external API, etc.) cannot stall the message pipeline. On timeout it logs a warning and returns fallback_value; on any other exception it logs an error (with traceback) and likewise returns the fallback.asyncio.CancelledErroris deliberately re-raised so task cancellation is never swallowed. The only side effect is a log line via this module’slogger.Called wherever a non-critical async dependency is invoked along the hot path; also covered directly by
tests/core/migration/test_dependency_guards.py.- Parameters:
coro (
Coroutine[Any,Any,Any]) – The coroutine to await under the timeout. It is consumed exactly once whether or not it completes in time.timeout_seconds (
float) – Maximum seconds to wait before falling back.fallback_value (
Any) – Value returned on timeout or error.service_name (
str) – Label for the guarded dependency, used in log messages.
- Returns:
The coroutine’s result on success, otherwise fallback_value.
- Return type:
- Raises:
asyncio.CancelledError – Always re-raised; cancellation is never caught.