Coverage for src/copytrading_engine/trading/adapters/capabilities.py: 85%

227 statements  

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

1"""Read-only connection checks required before a saved trading revision is activated.""" 

2 

3import asyncio 

4import difflib 

5import logging 

6from collections.abc import Awaitable, Callable 

7from typing import Literal, Protocol 

8 

9import discord 

10import httpx 

11from pydantic import BaseModel, ConfigDict, SecretStr 

12 

13from copytrading_engine.execution.adapters.alpaca.broker import AlpacaBroker, AlpacaCredentials 

14from copytrading_engine.parsing.providers.registry import ManagedDecoder, builtin_registry 

15from copytrading_engine.parsing.readiness import ModelReadiness, probe_model 

16from copytrading_engine.shared.cleanup import close_logged 

17from copytrading_engine.sources.source import require_history_channel 

18from copytrading_engine.trading.adapters.notifications import discord_webhook 

19from copytrading_engine.trading.domain.config import ( 

20 AccountConfiguration, 

21 BrokerCheck, 

22 BrokerCredentials, 

23 ConnectionCheck, 

24 ModelCheck, 

25 NotificationCheck, 

26 NotificationConfiguration, 

27 ProviderConfiguration, 

28 SourceCheck, 

29 SourceConfiguration, 

30 TradingConfiguration, 

31 TradingSecrets, 

32) 

33 

34log = logging.getLogger(__name__) 

35 

36type CapabilityState = Literal["ready", "failed", "not_configured"] 

37type CapabilityName = Literal["source", "model", "broker", "notification", "configuration"] 

38 

39 

40class CapabilityCheck(BaseModel): 

41 """Safe identity and permission evidence; never carries submitted credentials.""" 

42 

43 model_config = ConfigDict(extra="forbid", frozen=True) 

44 

45 name: CapabilityName 

46 state: CapabilityState 

47 subject: str | None = None 

48 environment: Literal["paper", "live"] | None = None 

49 identity: str | None = None 

50 adapter: str 

51 reason_code: str | None = None 

52 # A close name the provider lists, when the model asked for does not exist. 

53 suggestion: str | None = None 

54 # The stocks a configuration check is about, such as those a removed account still holds. 

55 symbols: tuple[str, ...] = () 

56 

57 

58class TradingCapabilityReport(BaseModel): 

59 model_config = ConfigDict(extra="forbid", frozen=True) 

60 

61 configuration_revision: str 

62 activatable: bool 

63 checks: tuple[CapabilityCheck, ...] 

64 cost_notice: str 

65 

66 

67class CapabilityProbes(Protocol): 

68 async def source(self, configuration: SourceConfiguration, token: str) -> CapabilityCheck: ... 

69 

70 async def model(self, configuration: ProviderConfiguration, token: str) -> CapabilityCheck: ... 

71 

72 async def broker( 

73 self, account: AccountConfiguration, credentials: BrokerCredentials 

74 ) -> CapabilityCheck: ... 

75 

76 async def notification( 

77 self, configuration: NotificationConfiguration | None, token: str | None 

78 ) -> CapabilityCheck: ... 

79 

80 

81def _refused_keys_reason(account: AccountConfiguration, credentials: BrokerCredentials) -> str: 

82 """Why keys the chosen environment refused were refused. Alpaca serves paper and live from 

83 separate servers that each accept only their own keys, so keys the other server accepts (one 

84 read-only account read) are that environment's keys: "broker_keys_are_paper" or 

85 "broker_keys_are_live". Otherwise the keys are simply refused.""" 

86 other = "live" if account.environment == "paper" else "paper" 

87 broker = None 

88 try: 

89 broker = AlpacaBroker(AlpacaCredentials(credentials.key, credentials.secret), other) 

90 broker.account() 

91 except Exception: # noqa: BLE001 - refused on both servers, or unreachable 

92 return "broker_auth_or_permissions_failed" 

93 finally: 

94 if broker is not None: 94 ↛ 96line 94 didn't jump to line 96 because the condition on line 94 was always true

95 broker.close() 

96 return f"broker_keys_are_{other}" 

97 

98 

99def _failed( 

100 name: CapabilityName, 

101 code: str, 

102 *, 

103 subject: str | None = None, 

104 environment: Literal["paper", "live"] | None = None, 

105 adapter: str = "connection_probe", 

106 suggestion: str | None = None, 

107) -> CapabilityCheck: 

108 return CapabilityCheck( 

109 name=name, 

110 state="failed", 

111 subject=subject, 

112 environment=environment, 

113 identity=None, 

114 adapter=adapter, 

115 reason_code=code, 

116 suggestion=suggestion, 

117 ) 

118 

119 

120async def _closest_model(decoder: ManagedDecoder, asked: str) -> str | None: 

121 """The listed model name nearest to a mistyped one, or nothing when the list is unavailable.""" 

122 try: 

123 names = await asyncio.wait_for(decoder.model_names(), timeout=15) 

124 except asyncio.CancelledError: 

125 raise 

126 except Exception: # noqa: BLE001 - a missing list only means no suggestion 

127 return None 

128 matches = difflib.get_close_matches(asked, names, n=1, cutoff=0.6) 

129 return matches[0] if matches else None 

130 

131 

132async def _safely( 

133 name: CapabilityName, 

134 operation: Awaitable[CapabilityCheck], 

135 *, 

136 subject: str | None = None, 

137 environment: Literal["paper", "live"] | None = None, 

138) -> CapabilityCheck: 

139 try: 

140 return await operation 

141 except asyncio.CancelledError: 

142 raise 

143 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check 

144 return _failed( 

145 name, f"{name}_capability_unavailable", subject=subject, environment=environment 

146 ) 

147 

148 

149class TradingCapabilityService: 

150 """Run source, provider, broker, and notification checks without saving config.""" 

151 

152 def __init__(self, probes: CapabilityProbes | None = None) -> None: 

153 self._probes = probes or NativeCapabilityProbes() 

154 

155 async def validate( 

156 self, configuration: TradingConfiguration, secrets: TradingSecrets 

157 ) -> TradingCapabilityReport: 

158 configuration = TradingConfiguration.model_validate(configuration.model_dump()) 

159 secrets = TradingSecrets.model_validate(secrets.model_dump()) 

160 by_account = {credential.account_id: credential for credential in secrets.brokers} 

161 account_ids = {account.id for account in configuration.accounts} 

162 checks: list[CapabilityCheck] = [] 

163 # An account without keys fails its own broker check below; keys for an account the 

164 # setup doesn't have are named here, once each. 

165 checks.extend( 

166 _failed("configuration", "broker_keys_without_account", subject=account_id) 

167 for account_id in sorted(set(by_account) - account_ids) 

168 ) 

169 

170 operations = [ 

171 _safely( 

172 "source", 

173 self._probes.source(configuration.source, secrets.discord_token.get_secret_value()), 

174 ), 

175 _safely( 

176 "model", 

177 self._probes.model( 

178 configuration.provider, secrets.provider_api_key.get_secret_value() 

179 ), 

180 ), 

181 _safely( 

182 "notification", 

183 self._probes.notification( 

184 configuration.notification, 

185 secrets.notification_token.get_secret_value() 

186 if secrets.notification_token is not None 

187 else None, 

188 ), 

189 ), 

190 ] 

191 for account in configuration.accounts: 

192 credentials = by_account.get(account.id) 

193 if credentials is None: 

194 operations.append( 

195 asyncio.sleep( 

196 0, 

197 result=_failed( 

198 "broker", 

199 "broker_credentials_missing", 

200 subject=account.id, 

201 environment=account.environment, 

202 ), 

203 ) 

204 ) 

205 else: 

206 operations.append( 

207 _safely( 

208 "broker", 

209 self._probes.broker(account, credentials), 

210 subject=account.id, 

211 environment=account.environment, 

212 ) 

213 ) 

214 checks.extend(await asyncio.gather(*operations)) 

215 activatable = all(check.state in {"ready", "not_configured"} for check in checks) 

216 return TradingCapabilityReport( 

217 configuration_revision=configuration.revision(), 

218 activatable=activatable, 

219 checks=tuple(checks), 

220 cost_notice=( 

221 "Model validation sends one short no-trade prompt to the configured provider; " 

222 "provider charges may apply. Notification validation checks bot/chat access " 

223 "without sending a message." 

224 ), 

225 ) 

226 

227 async def check(self, connection: ConnectionCheck) -> CapabilityCheck: 

228 """One service, the moment the owner connects it: the same read-only check a full 

229 validation runs for it, without saving anything or granting a start.""" 

230 match connection: 

231 case SourceCheck(): 

232 return await _safely( 

233 "source", 

234 self._probes.source(connection.source, connection.token.get_secret_value()), 

235 ) 

236 case ModelCheck(): 

237 return await _safely( 

238 "model", 

239 self._probes.model(connection.provider, connection.api_key.get_secret_value()), 

240 ) 

241 case BrokerCheck(): 

242 account = connection.account 

243 return await _safely( 

244 "broker", 

245 self._probes.broker(account, connection.credentials), 

246 subject=account.id, 

247 environment=account.environment, 

248 ) 

249 case NotificationCheck(): 249 ↛ exitline 249 didn't return from function 'check' because the pattern on line 249 always matched

250 return await _safely( 

251 "notification", 

252 self._probes.notification( 

253 connection.notification, connection.token.get_secret_value() 

254 ), 

255 ) 

256 

257 

258class NativeCapabilityProbes: 

259 """Actual read-only adapters used by the desktop engine.""" 

260 

261 def __init__( 

262 self, 

263 *, 

264 discord_client_factory: Callable[..., discord.Client] = discord.Client, 

265 http_client_factory: Callable[..., httpx.AsyncClient] = httpx.AsyncClient, 

266 source_timeout_seconds: float = 20, 

267 ) -> None: 

268 if source_timeout_seconds <= 0: 268 ↛ 269line 268 didn't jump to line 269 because the condition on line 268 was never true

269 raise ValueError("Source probe timeout must be positive") 

270 self._discord_client_factory = discord_client_factory 

271 self._http_client_factory = http_client_factory 

272 self._source_timeout_seconds = source_timeout_seconds 

273 

274 async def source(self, configuration: SourceConfiguration, token: str) -> CapabilityCheck: 

275 # discord.py-self does not expose discord.Intents. Its documented client 

276 # defaults are also what the existing DiscordSession adapter uses. 

277 client = self._discord_client_factory() 

278 stage = "login" 

279 try: 

280 async with asyncio.timeout(self._source_timeout_seconds): 

281 await client.login(token) 

282 user = client.user 

283 if user is None: 283 ↛ 284line 283 didn't jump to line 284 because the condition on line 283 was never true

284 return _failed("source", "source_identity_unavailable") 

285 for channel_id in configuration.channel_ids: 

286 stage = "channel" 

287 channel = await client.fetch_channel(int(channel_id)) 

288 try: 

289 readable = require_history_channel(channel) 

290 except ValueError: 

291 return _failed("source", "source_channel_not_readable") 

292 stage = "history" 

293 history = readable.history(limit=1) 

294 try: 

295 await anext(history, None) 

296 finally: 

297 close = getattr(history, "aclose", None) 

298 if close is not None: 298 ↛ 285line 298 didn't jump to line 285 because the condition on line 298 was always true

299 await close() 

300 return CapabilityCheck( 

301 name="source", 

302 state="ready", 

303 identity=f"discord_user:{user.id}", 

304 adapter="discord-py-self-user-token", 

305 reason_code=None, 

306 ) 

307 except asyncio.CancelledError: 

308 raise 

309 except TimeoutError: 

310 reason = ( 

311 "source_history_probe_timed_out" if stage == "history" else "source_probe_timed_out" 

312 ) 

313 return _failed("source", reason) 

314 except discord.Forbidden: 

315 reason = ( 

316 "source_history_permission_denied" 

317 if stage == "history" 

318 else "source_channel_access_denied" 

319 ) 

320 return _failed("source", reason) 

321 except discord.HTTPException: 

322 reason = ( 

323 "source_history_read_failed" 

324 if stage == "history" 

325 else "source_auth_or_channel_access" 

326 ) 

327 return _failed("source", reason) 

328 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check 

329 reason = ( 

330 "source_history_read_failed" 

331 if stage == "history" 

332 else "source_auth_or_channel_access" 

333 ) 

334 return _failed("source", reason) 

335 finally: 

336 await close_logged(client.close, resource="source_probe", log=log) 

337 

338 async def model(self, configuration: ProviderConfiguration, token: str) -> CapabilityCheck: 

339 decoder = None 

340 try: 

341 decoder = await builtin_registry().create( 

342 configuration.name, 

343 configuration.reader(SecretStr(token), timeout=20), 

344 ) 

345 health = ModelReadiness() 

346 await asyncio.wait_for(probe_model(decoder, health), timeout=25) 

347 if health.error == "provider_key_rejected": 

348 return _failed("model", "model_key_rejected", adapter=configuration.name) 

349 if health.error == "provider_model_not_found": 

350 return _failed( 

351 "model", 

352 "model_not_found", 

353 adapter=configuration.name, 

354 suggestion=await _closest_model(decoder, configuration.model), 

355 ) 

356 if health.error in {"provider_unavailable", "provider_timeout"}: 

357 return _failed("model", "model_unreachable", adapter=configuration.name) 

358 if not health.ready: 

359 return _failed("model", "model_probe_rejected", adapter=configuration.name) 

360 return CapabilityCheck( 

361 name="model", 

362 state="ready", 

363 identity=f"{configuration.name}:{configuration.model}", 

364 adapter=configuration.name, 

365 reason_code=None, 

366 ) 

367 except asyncio.CancelledError: 

368 raise 

369 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check 

370 return _failed("model", "model_auth_or_probe_failed", adapter=configuration.name) 

371 finally: 

372 if decoder is not None: 

373 await close_logged(decoder.close, resource="model_probe", log=log) 

374 

375 async def broker( 

376 self, account: AccountConfiguration, credentials: BrokerCredentials 

377 ) -> CapabilityCheck: 

378 return await asyncio.to_thread(self._broker_read, account, credentials) 

379 

380 @staticmethod 

381 def _broker_read( 

382 account: AccountConfiguration, credentials: BrokerCredentials 

383 ) -> CapabilityCheck: 

384 broker = None 

385 try: 

386 broker = AlpacaBroker( 

387 AlpacaCredentials(credentials.key, credentials.secret), account.environment 

388 ) 

389 identity = broker.account() 

390 if not identity.active: 390 ↛ 391line 390 didn't jump to line 391 because the condition on line 390 was never true

391 return _failed( 

392 "broker", 

393 "broker_account_not_tradeable", 

394 subject=account.id, 

395 environment=account.environment, 

396 adapter="alpaca_read_only", 

397 ) 

398 broker.positions() 

399 broker.open_orders() 

400 return CapabilityCheck( 

401 name="broker", 

402 state="ready", 

403 subject=account.id, 

404 environment=account.environment, 

405 identity=identity.id, 

406 adapter="alpaca_read_only", 

407 reason_code=None, 

408 ) 

409 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check 

410 return _failed( 

411 "broker", 

412 _refused_keys_reason(account, credentials), 

413 subject=account.id, 

414 environment=account.environment, 

415 adapter="alpaca_read_only", 

416 ) 

417 finally: 

418 if broker is not None: 

419 broker.close() 

420 

421 async def notification( 

422 self, configuration: NotificationConfiguration | None, token: str | None 

423 ) -> CapabilityCheck: 

424 if configuration is None: 424 ↛ 425line 424 didn't jump to line 425 because the condition on line 424 was never true

425 return CapabilityCheck( 

426 name="notification", 

427 state="not_configured", 

428 adapter="not_configured", 

429 reason_code=None, 

430 ) 

431 if token is None or not token: 431 ↛ 432line 431 didn't jump to line 432 because the condition on line 431 was never true

432 return _failed("notification", "notification_credentials_missing") 

433 if configuration.service == "discord": 

434 return await self._discord_webhook(token) 

435 try: 

436 async with self._http_client_factory(timeout=8, follow_redirects=False) as client: 

437 base = f"https://api.telegram.org/bot{token}" 

438 async with asyncio.timeout(10): 

439 bot_response = await client.get(f"{base}/getMe") 

440 bot_response.raise_for_status() 

441 bot_body = bot_response.json() 

442 if not isinstance(bot_body, dict) or bot_body.get("ok") is not True: 442 ↛ 443line 442 didn't jump to line 443 because the condition on line 442 was never true

443 return _failed("notification", "notification_bot_identity_failed") 

444 chat_response = await client.get( 

445 f"{base}/getChat", params={"chat_id": configuration.chat_id} 

446 ) 

447 chat_response.raise_for_status() 

448 chat_body = chat_response.json() 

449 if not isinstance(chat_body, dict) or chat_body.get("ok") is not True: 449 ↛ 450line 449 didn't jump to line 450 because the condition on line 449 was never true

450 return _failed("notification", "notification_chat_access_failed") 

451 bot = bot_body.get("result") 

452 chat = chat_body.get("result") 

453 if not isinstance(bot, dict) or not isinstance(chat, dict): 453 ↛ 454line 453 didn't jump to line 454 because the condition on line 453 was never true

454 return _failed("notification", "notification_identity_invalid") 

455 username = bot.get("username") 

456 chat_id = chat.get("id") 

457 if not isinstance(username, str) or type(chat_id) not in {int, str}: 457 ↛ 458line 457 didn't jump to line 458 because the condition on line 457 was never true

458 return _failed("notification", "notification_identity_invalid") 

459 return CapabilityCheck( 

460 name="notification", 

461 state="ready", 

462 identity=f"telegram_bot:@{username};chat:{chat_id}", 

463 adapter="telegram_read_only", 

464 reason_code=None, 

465 ) 

466 except asyncio.CancelledError: 

467 raise 

468 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check 

469 return _failed("notification", "notification_auth_or_chat_access_failed") 

470 

471 async def _discord_webhook(self, url: str) -> CapabilityCheck: 

472 """Reads the webhook's name and channel, which Discord answers without posting anything.""" 

473 adapter = "discord_webhook_read_only" 

474 try: 

475 host, path = discord_webhook(url) 

476 except ValueError: 

477 return _failed("notification", "notification_webhook_invalid", adapter=adapter) 

478 try: 

479 async with self._http_client_factory(timeout=8, follow_redirects=False) as client: 

480 async with asyncio.timeout(10): 

481 response = await client.get(f"https://{host}{path}") 

482 response.raise_for_status() 

483 body = response.json() 

484 except asyncio.CancelledError: 

485 raise 

486 except Exception: # noqa: BLE001 - the URL is the secret, so no detail is kept 

487 return _failed("notification", "notification_webhook_unreachable", adapter=adapter) 

488 name = body.get("name") if isinstance(body, dict) else None 

489 channel = body.get("channel_id") if isinstance(body, dict) else None 

490 if not isinstance(name, str) or not isinstance(channel, str): 490 ↛ 491line 490 didn't jump to line 491 because the condition on line 490 was never true

491 return _failed("notification", "notification_identity_invalid", adapter=adapter) 

492 return CapabilityCheck( 

493 name="notification", 

494 state="ready", 

495 identity=f"discord_webhook:{name};channel:{channel}", 

496 adapter=adapter, 

497 reason_code=None, 

498 )