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
« 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."""
3import asyncio
4import json
5from collections.abc import AsyncGenerator, AsyncIterable
6from contextlib import asynccontextmanager
7from typing import Any, Protocol
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
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
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]
49class _ListedModel(Protocol):
50 @property
51 def id(self) -> str: ...
54class _ModelPages(Protocol):
55 def list(self) -> AsyncIterable[_ListedModel]: ...
58class _ProviderClient(Protocol):
59 @property
60 def models(self) -> _ModelPages: ...
62 async def close(self) -> None: ...
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
79type ReaderAgent = Agent[ReadingInput, ReadingOutput | JustChat]
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
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)
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
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)
132 async def close(self) -> None:
133 await self.client.close()
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"
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
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."""
171 @agent.instructions
172 def instructions() -> str:
173 return INSTRUCTIONS
175 @agent.instructions
176 def playbook(context: RunContext[ReadingInput]) -> str | None:
177 return playbook_instructions(context.deps.route.playbook)
179 @agent.instructions
180 def recent_calls(context: RunContext[ReadingInput]) -> str | None:
181 return recent_calls_instructions(context.deps.recent)
183 return agent
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
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