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

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 urllib.parse import urlparse, urlunparse 

19 

20import httpx 

21import openai 

22 

23 

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

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

26 

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

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

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

30 """ 

31 if not base_url: 

32 return "<unknown>" 

33 try: 

34 parsed = urlparse(base_url) 

35 except Exception: 

36 return "<unknown>" 

37 if not parsed.netloc: 

38 return base_url 

39 host = parsed.hostname or "" 

40 # urlparse exposes IPv6 hostnames without their surrounding brackets; 

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

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

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

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

45 if ":" in host: 

46 host = f"[{host}]" 

47 if parsed.port: 

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

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

50 

51 

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

53 """Walk ``__cause__`` / ``__context__`` to find the deepest non-wrapper 

54 exception, with a cycle guard. 

55 

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

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

58 on. If the walk doesn't find anything more specific, the original is 

59 returned. 

60 """ 

61 seen: set[int] = set() 

62 cur: BaseException | None = exc 

63 deepest: BaseException = exc 

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

65 seen.add(id(cur)) 

66 deepest = cur 

67 cur = cur.__cause__ or cur.__context__ 

68 return deepest 

69 

70 

71_DOCKER_HINT = ( 

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

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

74 "the host network namespace)" 

75) 

76 

77 

78def _dispatch( 

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

80) -> tuple[str, str]: 

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

82 

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

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

85 is lost. 

86 """ 

87 

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

89 cls = getattr(openai, cls_name, None) 

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

91 

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

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

94 if _is("APITimeoutError") or isinstance(root, httpx.ReadTimeout): 

95 return ( 

96 "openai_timeout", 

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

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

99 ) 

100 

101 # Connection-refused / network-unreachable family 

102 if _is("APIConnectionError") or isinstance(root, httpx.ConnectError): 

103 return ( 

104 "openai_connection_refused", 

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

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

107 ) 

108 

109 # Auth 

110 if _is("AuthenticationError"): 

111 return ( 

112 "openai_auth", 

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

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

115 "key.", 

116 ) 

117 

118 # Permission denied 

119 if _is("PermissionDeniedError"): 

120 return ( 

121 "openai_permission_denied", 

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

123 ) 

124 

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

126 if _is("NotFoundError"): 

127 return ( 

128 "openai_model_not_found", 

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

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

131 ) 

132 

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

134 # because RateLimitError subclasses APIStatusError -> APIError. 

135 if _is("RateLimitError"): 

136 return ( 

137 "openai_rate_limit", 

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

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

140 "limiting in Settings.", 

141 ) 

142 

143 # Bad request (400) 

144 if _is("BadRequestError"): 

145 return ( 

146 "openai_bad_request", 

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

148 f"'{model}'.", 

149 ) 

150 

151 # Any other openai SDK error 

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

153 return ( 

154 "openai_unknown", 

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

156 ) 

157 

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

159 return ( 

160 "openai_unknown", 

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

162 ) 

163 

164 

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

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

167 ``openai.*`` / ``httpx.*`` runtime error we can rewrite. 

168 

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

170 :func:`friendly_openai_compatible_error` instead of the existing 

171 string-keyword branches. 

172 """ 

173 root = _walk_cause(exc) 

174 if isinstance(root, openai.APIError): 

175 return True 

176 if isinstance(root, (httpx.ConnectError, httpx.ReadTimeout)): 

177 return True 

178 return False 

179 

180 

181def friendly_openai_compatible_error( 

182 exc: BaseException, 

183 *, 

184 provider: str, 

185 base_url: str | None, 

186 model: str | None, 

187) -> str: 

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

189 

190 Returns a string of the form:: 

191 

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

193 

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

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

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

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

198 """ 

199 redacted = _strip_credentials(base_url) 

200 model_repr = model or "<unspecified>" 

201 provider_repr = provider or "<unknown provider>" 

202 root = _walk_cause(exc) 

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

204 return f"{friendly} (Error type: {code}) | Details: {exc!s}"