@@ -104,6 +104,8 @@ def close(self) -> None: ...
104104
105105 def set_timeout (self , timeout : float ) -> None : ...
106106
107+ def check_health (self , timeout : float = 15.0 ) -> tuple [bool , str ]: ...
108+
107109
108110# serializes appends to the shared LLM log file: concurrent sub-agents
109111# (each with its own client but ONE shared log_path, see Client.clone)
@@ -518,6 +520,60 @@ def set_timeout(self, timeout: float) -> None:
518520 self .timeout = timeout
519521 self ._reset_http ()
520522
523+ def check_health (self , timeout : float = 15.0 ) -> tuple [bool , str ]:
524+ """Minimal probe: send a tiny chat completion to verify the model works.
525+
526+ Returns ``(available, message)``. Does not retry — this is a
527+ probe, not a request the user is waiting on. Uses a temporary
528+ httpx client so it never interferes with the main pool.
529+
530+ A chat completion request is the only reliable way to verify a
531+ specific model is actually usable: the ``/models`` endpoint can
532+ be stale, incomplete, or return IDs that differ from what the
533+ completions endpoint accepts.
534+ """
535+ try :
536+ with httpx .Client (timeout = timeout , verify = _httpx_verify (self .verify )) as probe :
537+ resp = probe .post (
538+ f"{ self .base_url } /chat/completions" ,
539+ headers = self ._headers (stream = False ),
540+ # no token limit: reasoning models reject ``max_tokens``
541+ # (they want ``max_completion_tokens``), and chat() sends
542+ # none by default either
543+ json = {
544+ "model" : self .model ,
545+ "messages" : [{"role" : "user" , "content" : "hi" }],
546+ "stream" : False ,
547+ },
548+ )
549+ try :
550+ body = resp .json ()
551+ except ValueError :
552+ body = None
553+ # 3xx is not success: redirects aren't followed, so an SSO or
554+ # captive-portal redirect must not read as a working model
555+ if 200 <= resp .status_code < 300 :
556+ # some gateways report failures as 200 + {"error": ...}
557+ err = _error_text (body ) if isinstance (body , dict ) else None
558+ if err :
559+ return False , f"HTTP { resp .status_code } : { err [:80 ]} "
560+ return True , "ok"
561+ # not AUTH_REFRESH_STATUS_CODES: it may include 502, which here
562+ # means the backend is down, not that the key expired
563+ if resp .status_code in (401 , 403 ):
564+ return False , f"auth error ({ resp .status_code } )"
565+ if resp .status_code == 429 :
566+ return False , "rate limited (429)"
567+ if isinstance (body , dict ):
568+ msg = _error_text (body ) or body .get ("message" )
569+ if msg :
570+ return False , f"HTTP { resp .status_code } : { str (msg )[:80 ]} "
571+ return False , f"HTTP { resp .status_code } "
572+ except httpx .HTTPError as e :
573+ return False , f"unreachable: { type (e ).__name__ } "
574+ except OSError as e :
575+ return False , f"unreachable: { type (e ).__name__ } "
576+
521577 def _refresh_api_key (
522578 self ,
523579 cancel_check : Callable [[], bool ] | None = None ,
0 commit comments