Coverage for src/copytrading_engine/parsing/providers/pydantic_ai.py: 91%

111 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-11-16 16:55 +0000

1"""Provider-neutral decoding and safe error translation for PydanticAI.""" 

2 

3import asyncio 

4import json 

5from collections.abc import AsyncGenerator, AsyncIterable 

6from contextlib import asynccontextmanager 

7from typing import Any, Protocol 

8 

9import pydantic_ai 

10from pydantic_ai import Agent, ModelRetry, PromptedOutput, RunContext 

11from pydantic_ai.exceptions import ( 

12 ModelAPIError, 

13 ModelHTTPError, 

14 UnexpectedModelBehavior, 

15 UsageLimitExceeded, 

16) 

17from pydantic_ai.models import Model 

18from pydantic_ai.settings import ModelSettings 

19from pydantic_ai.usage import UsageLimits 

20 

21from copytrading_engine.parsing.diagnostics import validation_issues 

22from copytrading_engine.parsing.extraction import ( 

23 Answer, 

24 DecodeError, 

25 GroundingError, 

26 JustChat, 

27 ReadingInput, 

28 ReadingOutput, 

29 check_reading, 

30 check_references, 

31 check_summary_language, 

32 without_cross_side_repeats, 

33) 

34from copytrading_engine.parsing.history import RecentCall 

35from copytrading_engine.parsing.learning import PlaybookProposal 

36from copytrading_engine.parsing.prompt import ( 

37 INSTRUCTIONS, 

38 playbook_instructions, 

39 recent_calls_instructions, 

40) 

41from copytrading_engine.parsing.routes import Route 

42from copytrading_engine.shared.reading import Chatter 

43 

44# The engine owns its output: its stdout and stderr are the app's pipe and log. The library 

45# leaves the flag unannotated, so its type is inferred as the literal True. 

46pydantic_ai.BANNER_ENABLED = False # ty: ignore[invalid-assignment] 

47 

48 

49class _ListedModel(Protocol): 

50 @property 

51 def id(self) -> str: ... 

52 

53 

54class _ModelPages(Protocol): 

55 def list(self) -> AsyncIterable[_ListedModel]: ... 

56 

57 

58class _ProviderClient(Protocol): 

59 @property 

60 def models(self) -> _ModelPages: ... 

61 

62 async def close(self) -> None: ... 

63 

64 

65# Words a provider uses when a request names a model it does not have. DeepSeek, for one, says 

66# "The supported API model names are …, but you passed …". 

67_UNKNOWN_MODEL = ( 

68 "not exist", 

69 "not found", 

70 "invalid model", 

71 "unknown model", 

72 "no such model", 

73 "model names are", 

74 "you passed", 

75) 

76_MODEL_NAME_LIMIT = 2000 

77 

78 

79type ReaderAgent = Agent[ReadingInput, ReadingOutput | JustChat] 

80 

81 

82class PydanticAIDecoder: 

83 def __init__( 

84 self, 

85 agent: ReaderAgent, 

86 learner: Agent[None, PlaybookProposal], 

87 client: _ProviderClient, 

88 timeout: float, 

89 *, 

90 connection_errors: tuple[type[Exception], ...] = (), 

91 ) -> None: 

92 self.agent = agent 

93 self.learner = learner 

94 self.client = client 

95 self.timeout = timeout 

96 self.connection_errors = connection_errors 

97 

98 async def answer(self, text: str, route: Route, recent: tuple[RecentCall, ...] = ()) -> Answer: 

99 async with _translated_errors(self.connection_errors): 

100 async with asyncio.timeout(self.timeout): 

101 # A reading that fails a check goes back once with the reason, then to review. 

102 result = await self.agent.run( 

103 json.dumps({"message": text}, ensure_ascii=False), 

104 deps=ReadingInput(text=text, route=route, recent=recent), 

105 usage_limits=UsageLimits(request_limit=2, output_tokens_limit=6000), 

106 ) 

107 output = result.output 

108 return Answer(Chatter() if isinstance(output, JustChat) else output.reading) 

109 

110 async def learn(self, posts: tuple[str, ...]) -> PlaybookProposal: 

111 async with _translated_errors(self.connection_errors): 

112 async with asyncio.timeout(self.timeout): 

113 # One retry: a long draft occasionally comes back as invalid JSON. 

114 result = await self.learner.run( 

115 json.dumps({"posts": list(posts)}, ensure_ascii=False), 

116 usage_limits=UsageLimits(request_limit=2, output_tokens_limit=16000), 

117 ) 

118 return result.output 

119 

120 async def model_names(self) -> tuple[str, ...]: 

121 """The model names the provider lists for this key, as the owner would type them.""" 

122 async with _translated_errors(self.connection_errors): 

123 async with asyncio.timeout(self.timeout): 

124 names: list[str] = [] 

125 async for listed in self.client.models.list(): 

126 # Google lists "models/gemini-2.5-flash" but is asked for "gemini-2.5-flash". 

127 names.append(listed.id.removeprefix("models/")) 

128 if len(names) >= _MODEL_NAME_LIMIT: 128 ↛ 129line 128 didn't jump to line 129 because the condition on line 128 was never true

129 break 

130 return tuple(names) 

131 

132 async def close(self) -> None: 

133 await self.client.close() 

134 

135 

136def _rejection(exc: ModelHTTPError) -> str: 

137 """Name what a provider refused: the key, the model name, or something else in the request.""" 

138 if exc.status_code in {401, 403}: 

139 return "provider_key_rejected" 

140 text = json.dumps(exc.body, default=str).lower() if exc.body is not None else "" 

141 # The answer is about the model name only when it quotes the name back and calls it unknown; 

142 # a 404 that names no model is a wrong address. 

143 quotes_name = bool(exc.model_name) and exc.model_name.lower() in text 

144 if exc.status_code in {400, 404} and quotes_name and any(w in text for w in _UNKNOWN_MODEL): 

145 return "provider_model_not_found" 

146 return "provider_rejected" 

147 

148 

149def reading_agent(model: Model, model_settings: ModelSettings) -> ReaderAgent: 

150 """The reader every provider shares: one reading per post, held to the post's own words, or 

151 chat, which carries nothing. The answer is JSON asked for in the prompt (ADR-0012).""" 

152 agent: ReaderAgent = framed( 

153 Agent[ReadingInput, ReadingOutput | JustChat]( 

154 model, 

155 name="post_reader", 

156 output_type=PromptedOutput[ReadingOutput | JustChat]([ReadingOutput, JustChat]), 

157 deps_type=ReadingInput, 

158 retries=1, 

159 model_settings=model_settings, 

160 ) 

161 ) 

162 agent.output_validator(_checked) 

163 return agent 

164 

165 

166def framed[A: Agent[ReadingInput, Any]](agent: A) -> A: 

167 """The question every read of a post is asked in: the fixed instructions first, then the 

168 guru's playbook, then the guru's recent calls, so a provider can cache the part that does not 

169 change from post to post.""" 

170 

171 @agent.instructions 

172 def instructions() -> str: 

173 return INSTRUCTIONS 

174 

175 @agent.instructions 

176 def playbook(context: RunContext[ReadingInput]) -> str | None: 

177 return playbook_instructions(context.deps.route.playbook) 

178 

179 @agent.instructions 

180 def recent_calls(context: RunContext[ReadingInput]) -> str | None: 

181 return recent_calls_instructions(context.deps.recent) 

182 

183 return agent 

184 

185 

186def _checked( 

187 context: RunContext[ReadingInput], output: ReadingOutput | JustChat 

188) -> ReadingOutput | JustChat: 

189 """Holds the model to the post's own words and to the calls it was shown; a failure gives it 

190 one retry with the reason. Chat on the retry would let go a post the reader already took for 

191 something, so it ends the run instead, and the post waits for the owner.""" 

192 if isinstance(output, JustChat): 192 ↛ 193line 192 didn't jump to line 193 because the condition on line 192 was never true

193 if context.retry > 0: 

194 raise UnexpectedModelBehavior("A post read as something was answered as chat on retry") 

195 return output 

196 output = output.model_copy( 

197 update={"reading": without_cross_side_repeats(output.reading, context.deps.recent)} 

198 ) 

199 try: 

200 check_reading(output.reading, context.deps.text, context.deps.route) 

201 except GroundingError as exc: 

202 raise ModelRetry(f"{exc.issue.path}: {exc}") from None 

203 problem = check_references(output.reading, context.deps.recent) or check_summary_language( 

204 output.reading, context.deps.text, retried=context.retry > 0 

205 ) 

206 if problem is not None: 

207 raise ModelRetry(problem) 

208 return output 

209 

210 

211@asynccontextmanager 

212async def _translated_errors( 

213 connection_errors: tuple[type[Exception], ...], 

214) -> AsyncGenerator[None]: 

215 """Turn provider failures into DecodeError without keeping responses or secrets.""" 

216 try: 

217 yield 

218 except DecodeError: 

219 raise 

220 except ModelHTTPError as exc: 

221 retryable = exc.status_code == 429 or exc.status_code >= 500 

222 raise DecodeError( 

223 "provider_unavailable" if retryable else _rejection(exc), retryable=retryable 

224 ) from None 

225 except TimeoutError: 

226 raise DecodeError("provider_timeout", retryable=True) from None 

227 except connection_errors: 

228 raise DecodeError("provider_timeout", retryable=True) from None 

229 except ModelAPIError as exc: 

230 reason = ( 

231 "provider_timeout" 

232 if connection_errors and isinstance(exc.__cause__, connection_errors) 

233 else "provider_unavailable" 

234 ) 

235 raise DecodeError(reason, retryable=True) from None 

236 except UsageLimitExceeded: 

237 raise DecodeError("model_output_budget_exceeded", retryable=False) from None 

238 except UnexpectedModelBehavior as exc: 

239 raise DecodeError( 

240 "invalid_model_output", retryable=False, issues=validation_issues(exc) 

241 ) from None