Coverage for src/local_deep_research/error_handling/openai_compat_errors.py: 94%

1"""Friendly runtime-error rewriter for OpenAI-compatible LLM endpoints. 

2 

3When LM Studio, vLLM, llama.cpp server, OpenRouter, or any other OpenAI-compatible 

4provider fails at request time, the underlying `openai.*` / `httpx.*` exception 

5typically does not name the provider, configured base URL, or model in its 

6message. This helper walks the cause chain to find the root SDK exception and 

7produces a message that includes that context, while preserving the existing 

8``Error type: <code>`` token convention used downstream in research_service.py 

9and ErrorReporter. 

10 

11The helper deliberately does NOT introduce a new exception class -- the rest of 

12the pipeline is string-based today and tokens are how Sites B and C 

13communicate. 

14""" 

15 

16from __future__ import annotations 

17 

18from types import ModuleType 

19from urllib.parse import urlparse, urlunparse 

20 

21import httpx 

22import openai 

23 

24from ..security.log_sanitizer import sanitize_error_message 

25 

26# openai 3.x makes its requests through httpx2, so its transport errors are 

27# httpx2 classes and are unrelated to the httpx ones imported above. openai 2.x 

28# does not pull httpx2 in, so the import has to stay optional. 

29_TRANSPORT_MODULES: tuple[ModuleType, ...] = (httpx,) 

30try: 

31 import httpx2 

32except ImportError: 

33 pass 

34else: 

35 _TRANSPORT_MODULES += (httpx2,) 

36_CONNECT_ERRORS = tuple(m.ConnectError for m in _TRANSPORT_MODULES) 

37_READ_TIMEOUTS = tuple(m.ReadTimeout for m in _TRANSPORT_MODULES) 

38 

39 

40def _strip_credentials(base_url: str | None) -> str: 

41 """Return ``base_url`` with any userinfo (``user:password@``) removed. 

42 

43 Users sometimes embed an API key directly in the base URL (e.g. 

44 ``https://user:key@host/v1``). We must never echo that back to the UI or 

45 logs. Falsy / unparseable inputs are returned as ``"<unknown>"``. 

46 """ 

47 if not base_url: 

48 return "<unknown>" 

49 try: 

50 parsed = urlparse(base_url) 

51 except Exception: 

52 return "<unknown>" 

53 if not parsed.netloc: 

54 return base_url 

55 host = parsed.hostname or "" 

56 # urlparse exposes IPv6 hostnames without their surrounding brackets; 

57 # re-add them when reassembling the netloc, or the rebuilt URL is 

58 # not parseable by downstream HTTP libraries (e.g. ``http://::1:8080/`` 

59 # is ambiguous: is the host ``::`` and the port ``1:8080``?). IPv4 

60 # never contains ``:`` so this heuristic is safe. 

61 if ":" in host: 

62 host = f"[{host}]" 

63 if parsed.port: 

64 host = f"{host}:{parsed.port}" 

65 return urlunparse(parsed._replace(netloc=host)) or "<unknown>" 

66 

67 

68def _is_dispatchable(exc: BaseException) -> bool: 

69 """Return True when :func:`_dispatch` has a branch for ``exc``.""" 

70 return isinstance(exc, (openai.APIError, *_CONNECT_ERRORS, *_READ_TIMEOUTS)) 

71 

72 

73def _walk_cause(exc: BaseException) -> BaseException: 

74 """Walk ``__cause__`` / ``__context__`` for the outermost exception 

75 :func:`_dispatch` recognises, with a cycle guard. 

76 

77 LangChain often wraps the underlying ``openai.*`` exception in a generic 

78 ``Exception`` or ``RuntimeError``; we need the original class to dispatch 

79 on. The walk stops there rather than running to the end of the chain, 

80 because the SDK re-raises from its transport library and the transport 

81 re-raises from ``httpcore`` or a bare ``OSError``: a refused connection 

82 ends in ``ConnectionRefusedError``, which names no provider and no failure 

83 kind. If nothing in the chain is recognised the deepest exception is 

84 returned, as before. 

85 """ 

86 seen: set[int] = set() 

87 cur: BaseException | None = exc 

88 deepest: BaseException = exc 

89 while cur is not None and id(cur) not in seen: 

90 seen.add(id(cur)) 

91 if _is_dispatchable(cur): 

92 return cur 

93 deepest = cur 

94 cur = cur.__cause__ or cur.__context__ 

95 return deepest 

96 

97 

98_DOCKER_HINT = ( 

99 " (from inside Docker, localhost is the container itself -- use " 

100 "host.docker.internal, the host IP, or run with --network=host to share " 

101 "the host network namespace)" 

102) 

103 

104 

105def _dispatch( 

106 root: BaseException, provider: str, base_url: str, model: str 

107) -> tuple[str, str]: 

108 """Map a root exception to ``(error_code_token, friendly_message)``. 

109 

110 Returns ``("openai_unknown", <generic message>)`` for any exception we don't 

111 recognise; callers should still suffix the original ``exc!s`` so no detail 

112 is lost. 

113 """ 

114 

115 def _is(cls_name: str) -> bool: 

116 cls = getattr(openai, cls_name, None) 

117 return cls is not None and isinstance(root, cls) 

118 

119 # Timeout family -- must be checked BEFORE APIConnectionError because 

120 # openai.APITimeoutError subclasses APIConnectionError in openai>=1.x. 

121 if _is("APITimeoutError") or isinstance(root, _READ_TIMEOUTS): 

122 return ( 

123 "openai_timeout", 

124 f"{provider} at {base_url} did not respond in time. The server " 

125 "may be loading a model or overloaded.", 

126 ) 

127 

128 # Connection-refused / network-unreachable family 

129 if _is("APIConnectionError") or isinstance(root, _CONNECT_ERRORS): 

130 return ( 

131 "openai_connection_refused", 

132 f"Cannot reach {provider} at {base_url}. Check that the server " 

133 f"is running and the URL is correct.{_DOCKER_HINT}", 

134 ) 

135 

136 # Auth 

137 if _is("AuthenticationError"): 

138 return ( 

139 "openai_auth", 

140 f"{provider} rejected the API key for {base_url}. Local servers " 

141 "usually accept any non-empty key; remote providers need a valid " 

142 "key.", 

143 ) 

144 

145 # Permission denied 

146 if _is("PermissionDeniedError"): 

147 return ( 

148 "openai_permission_denied", 

149 f"{provider} denied access at {base_url} for model '{model}'.", 

150 ) 

151 

152 # Model not found (404 from OpenAI-compatible servers) 

153 if _is("NotFoundError"): 

154 return ( 

155 "openai_model_not_found", 

156 f"{provider} at {base_url} does not have model '{model}'. Pick a " 

157 f"model currently loaded in {provider}.", 

158 ) 

159 

160 # Rate limit (429) -- must be checked before the APIError catch-all 

161 # because RateLimitError subclasses APIStatusError -> APIError. 

162 if _is("RateLimitError"): 

163 return ( 

164 "openai_rate_limit", 

165 f"{provider} at {base_url} rate-limited the request for model " 

166 f"'{model}'. Wait a moment and retry, or enable LLM rate " 

167 "limiting in Settings.", 

168 ) 

169 

170 # Bad request (400) 

171 if _is("BadRequestError"): 

172 return ( 

173 "openai_bad_request", 

174 f"{provider} rejected the request to {base_url} for model " 

175 f"'{model}'.", 

176 ) 

177 

178 # Any other openai SDK error 

179 if _is("APIError"): 179 ↛ 180line 179 didn't jump to line 180 because the condition on line 179 was never true

180 return ( 

181 "openai_unknown", 

182 f"{provider} at {base_url} returned an error for model '{model}'.", 

183 ) 

184 

185 # Not an openai/httpx class we recognise -- caller should fall through. 

186 return ( 

187 "openai_unknown", 

188 f"{provider} at {base_url} returned an error for model '{model}'.", 

189 ) 

190 

191 

192def is_openai_compat_runtime_error(exc: BaseException) -> bool: 

193 """Return True iff ``exc`` (or any exception in its cause chain) is an 

194 ``openai.*`` or transport runtime error we can rewrite. 

195 

196 Used at Site B in research_service.py to decide whether to call 

197 :func:`friendly_openai_compatible_error` instead of the existing 

198 string-keyword branches. 

199 """ 

200 return _is_dispatchable(_walk_cause(exc)) 

201 

202 

203def friendly_openai_compatible_error( 

204 exc: BaseException, 

205 *, 

206 provider: str, 

207 base_url: str | None, 

208 model: str | None, 

209) -> str: 

210 """Build a user-facing error message for an OpenAI-compatible failure. 

211 

212 Returns a string of the form:: 

213 

214 <friendly message> (Error type: <code>) | Details: <original exc> 

215 

216 where ``<code>`` is one of the ``openai_*`` tokens that Site C and 

217 :class:`~local_deep_research.error_handling.error_reporter.ErrorReporter` 

218 recognise. The original exception text is always preserved in the 

219 ``Details:`` suffix so the user (and our logs) never lose information. 

220 """ 

221 redacted = _strip_credentials(base_url) 

222 model_repr = model or "<unspecified>" 

223 provider_repr = provider or "<unknown provider>" 

224 root = _walk_cause(exc) 

225 code, friendly = _dispatch(root, provider_repr, redacted, model_repr) 

226 return f"{friendly} (Error type: {code}) | Details: {sanitize_error_message(str(exc))}"