Coverage for downtify/doctor_ai.py: 90%

444 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""The Doctor's AI helper: an MCP server an AI assistant connects to. 

2 

3An admin starts it in Settings > Doctor > AI helper when they want an 

4assistant (Claude Code, Claude Desktop, any MCP client) to help clean up 

5the library, and stops it when they are done. While it runs, the 

6assistant can read what the Doctor found, run a health check, compare 

7playlists song by song, and *suggest* repairs with its reasons. The 

8suggestions show on the Doctor page as the usual cards, and run only 

9when the admin presses Apply there, or, when the admin switched it on, 

10when the assistant applies what the user agreed to in the chat. 

11 

12Everything an assistant changes goes through the Doctor's own repairs 

13(:mod:`downtify.doctor_routes`), so its checks, backups and "check 

14again first" locks still hold. 

15 

16The server speaks the MCP "Streamable HTTP" transport in its simplest 

17form: one ``POST`` per JSON-RPC message, answered with plain JSON (no 

18event stream, no sessions). Only what tools need is implemented: 

19``initialize``, ``ping``, ``tools/list`` and ``tools/call``. 

20 

21The helper is off until started, holds its state in memory only (a 

22restart turns it off and forgets its suggestions), and stops by itself 

23after :data:`IDLE_STOP` seconds without a request from the assistant. 

24Each start makes a new key; stopping throws it away. 

25""" 

26 

27from __future__ import annotations 

28 

29import asyncio 

30import hmac 

31import json 

32import secrets 

33import threading 

34import time 

35from collections.abc import Awaitable, Callable 

36from datetime import datetime, timezone 

37from pathlib import PurePosixPath 

38from typing import Any, Optional 

39 

40from fastapi import HTTPException 

41from loguru import logger 

42 

43from . import __version__, doctor_routes 

44 

45#: The helper stops by itself after this long without an AI request. 

46IDLE_STOP = 2 * 60 * 60 

47 

48#: MCP protocol revisions this server answers to, newest first. 

49PROTOCOL_VERSIONS = ('2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05') 

50 

51#: At most this many suggestions wait at once. 

52MAX_SUGGESTIONS = 500 

53 

54#: Longest reason kept from the assistant. 

55MAX_REASON = 2000 

56 

57#: Songs listed per page by ``get_playlist`` / per side by ``compare``. 

58PAGE = 200 

59 

60# JSON-RPC error codes. 

61PARSE_ERROR = -32700 

62INVALID_REQUEST = -32600 

63METHOD_NOT_FOUND = -32601 

64INVALID_PARAMS = -32602 

65 

66 

67def _now_iso() -> str: 

68 return datetime.now(timezone.utc).isoformat() 

69 

70 

71class Helper: 

72 """Whether the helper runs, its key, and the assistant's suggestions.""" 

73 

74 def __init__(self, clock: Callable[[], float] = time.monotonic) -> None: 

75 self._clock = clock 

76 self._lock = threading.Lock() 

77 self.token = '' 

78 self.started_at = '' 

79 self.last_used = 0.0 

80 self.last_used_at = '' 

81 self.client = '' 

82 self.can_apply = False 

83 self.user_id = 0 

84 self.suggestions: list[dict[str, Any]] = [] 

85 

86 # -- running --------------------------------------------------------- 

87 

88 @property 

89 def running(self) -> bool: 

90 with self._lock: 

91 return self._running_locked() 

92 

93 def _running_locked(self) -> bool: 

94 if not self.token: 

95 return False 

96 if self._clock() - self.last_used > IDLE_STOP: 

97 logger.info('doctor ai: stopped after {} s idle', IDLE_STOP) 

98 self._stop_locked() 

99 return False 

100 return True 

101 

102 def start(self, user_id: int = 0) -> str: 

103 """Start (or restart) with a new key; old suggestions are kept. 

104 *user_id* (the admin who started it) owns what the helper does.""" 

105 

106 with self._lock: 

107 self.user_id = int(user_id or 0) 

108 self.token = 'dtai_' + secrets.token_urlsafe(32) 

109 self.started_at = _now_iso() 

110 self.last_used = self._clock() 

111 self.last_used_at = '' 

112 self.client = '' 

113 self.can_apply = False 

114 return self.token 

115 

116 def stop(self) -> None: 

117 with self._lock: 

118 self._stop_locked() 

119 

120 def _stop_locked(self) -> None: 

121 self.token = '' 

122 self.started_at = '' 

123 self.client = '' 

124 self.can_apply = False 

125 

126 def check(self, header: str) -> bool: 

127 """Whether an ``Authorization`` header carries the current key; 

128 a good one counts as activity.""" 

129 

130 scheme, _, value = str(header or '').partition(' ') 

131 with self._lock: 

132 if not self._running_locked() or scheme.lower() != 'bearer': 

133 return False 

134 if not hmac.compare_digest(value.strip(), self.token): 

135 return False 

136 self.last_used = self._clock() 

137 self.last_used_at = _now_iso() 

138 return True 

139 

140 def set_client(self, info: Any) -> None: 

141 if isinstance(info, dict): 

142 name = str(info.get('name') or '').strip()[:80] 

143 version = str(info.get('version') or '').strip()[:40] 

144 with self._lock: 

145 self.client = f'{name} {version}'.strip() 

146 

147 def status(self) -> dict[str, Any]: 

148 with self._lock: 

149 running = self._running_locked() 

150 idle_left = ( 

151 max(0, int(IDLE_STOP - (self._clock() - self.last_used))) 

152 if running 

153 else 0 

154 ) 

155 return { 

156 'running': running, 

157 'key': self.token if running else '', 

158 'started_at': self.started_at, 

159 'last_used_at': self.last_used_at, 

160 'client': self.client, 

161 'stops_in': idle_left, 

162 'can_apply': self.can_apply, 

163 'suggestions': [dict(s) for s in self.suggestions], 

164 } 

165 

166 # -- suggestions ----------------------------------------------------- 

167 

168 def add(self, suggestion: dict[str, Any]) -> dict[str, Any]: 

169 with self._lock: 

170 waiting = [s for s in self.suggestions if s['state'] == 'waiting'] 

171 if len(waiting) >= MAX_SUGGESTIONS: 

172 raise ValueError('too_many_suggestions') 

173 taken = {p for s in waiting for p in s['paths']} 

174 clash = sorted(set(suggestion['paths']) & taken) 

175 if clash: 

176 raise ValueError(f'already_suggested:{clash[0]}') 

177 entry = { 

178 'id': secrets.token_hex(4), 

179 'state': 'waiting', 

180 'created_at': _now_iso(), 

181 'job': '', 

182 'error': None, 

183 **suggestion, 

184 } 

185 self.suggestions.append(entry) 

186 return dict(entry) 

187 

188 def waiting(self, ids: Optional[list[str]] = None) -> list[dict[str, Any]]: 

189 with self._lock: 

190 wanted = set(ids) if ids is not None else None 

191 return [ 

192 dict(s) 

193 for s in self.suggestions 

194 if s['state'] == 'waiting' 

195 and (wanted is None or s['id'] in wanted) 

196 ] 

197 

198 def update(self, ids: list[str], **fields: Any) -> None: 

199 with self._lock: 

200 for s in self.suggestions: 

201 if s['id'] in ids: 

202 s.update(fields) 

203 

204 def remove(self, ids: list[str]) -> int: 

205 """Drop waiting suggestions (dismissed or withdrawn).""" 

206 

207 with self._lock: 

208 before = len(self.suggestions) 

209 self.suggestions = [ 

210 s 

211 for s in self.suggestions 

212 if not (s['id'] in ids and s['state'] == 'waiting') 

213 ] 

214 return before - len(self.suggestions) 

215 

216 def clear_finished(self) -> int: 

217 with self._lock: 

218 before = len(self.suggestions) 

219 self.suggestions = [ 

220 s 

221 for s in self.suggestions 

222 if s['state'] in {'waiting', 'applying'} 

223 ] 

224 return before - len(self.suggestions) 

225 

226 

227helper = Helper() 

228 

229 

230# --------------------------------------------------------------------------- 

231# What the assistant is told 

232# --------------------------------------------------------------------------- 

233 

234INSTRUCTIONS = """\ 

235You are connected to the Doctor of a Downtify server: a self-hosted 

236music library (Spotify playlists downloaded as files, with M3U playlist 

237files that Navidrome and other players read). The Doctor finds leftover 

238problems; this helper lets you look at them, reason about them, and 

239suggest repairs that the user approves. Its sections: 

240 

241- DUPLICATE PLAYLISTS: M3U files that hold one playlist. A merge keeps 

242 the file Downtify writes today ("keeper"), puts every song of all of 

243 them in it once, keeps a cover, backs the others up to 

244 /data/doctor/backups/<date>/ and removes them. Allowed only when 80% 

245 of the smaller playlist's songs are in the larger one. "Different 

246 playlists" just stops the Doctor listing a group. 

247- DUPLICATE SONGS: copies of one song. "Keep this copy" moves 

248 everything that used the others (playlists, likes, watches, the 

249 Spotify id index) onto the kept file, then removes the others: to the 

250 music trash (restorable for 30 days) when it is on, for good 

251 otherwise. The Doctor only groups copies with the same artist, title 

252 and length; use search_library to find remixes, live, sped-up or 

253 other versions, and song_details, compare_audio and 

254 lookup_musicbrainz (official releases, lengths, ISRCs) to tell the 

255 original from the rest. With the music trash on, a copy it can't 

256 identify (no id or ISRC, and no full title/artist/album tags) can't 

257 be removed: song_details says so per copy, and suggest_keep_song 

258 refuses it up front. 

259- NEW SPOTIFY ID REPEATS: songs a watch downloaded again because Spotify 

260 gave them a new id; fix them with "keep this copy". 

261- SLSKD LEFTOVERS: files left in slskd's folder after import. Only 

262 leftovers verified to hold the same audio as a library file can be 

263 deleted. run_slskd_check holds new downloads until they are cleaned; 

264 call resume_downloads when nothing will be cleaned now. 

265- NAVIDROME: playlists Navidrome shows twice (an imported M3U and 

266 Downtify's API copy), imports whose M3U is gone, and more. Only 

267 playlists the health check flagged can be deleted. 

268 

269Work like this: 

2701. Call get_overview. If there is no health check, it is old, or a 

271 section you need is out of date, call run_health_check. 

2722. Look at the section the user cares about. Explain each finding in 

273 plain words (names, counts, lengths, what differs) and what you 

274 recommend and why. Ask when the user's wishes are unclear: what 

275 "official" or "the one to keep" means can depend on them. 

2763. Record each decision with a suggest_* tool and a short reason 

277 written for the user. Suggestions show in Downtify under Settings > 

278 Doctor > AI helper as the Doctor's usual cards (covers, players, 

279 counts), where the user presses Apply. 

2804. Only call apply_suggestions when get_overview says you may 

281 (ai_can_apply) AND the user clearly agreed in this chat to exactly 

282 those suggestions. Apply one section at a time: a repair puts other 

283 sections out of date until the next health check. 

284 

285Paths are relative to the downloads folder. Keep answers short and 

286readable: names, counts and lengths, not raw JSON. 

287""" 

288 

289 

290# --------------------------------------------------------------------------- 

291# Tools 

292# --------------------------------------------------------------------------- 

293 

294 

295class ToolError(Exception): 

296 """A tool call the assistant should correct (shown to it as text).""" 

297 

298 

299def _doctor(): 

300 """The Doctor's routes module (a function, so tests can swap it).""" 

301 

302 return doctor_routes 

303 

304 

305def _norm(path: Any) -> str: 

306 return str(path or '').strip().replace('\\', '/').lstrip('/') 

307 

308 

309def _song_name(stored: str) -> str: 

310 """``Artist - Title`` as the file name says, without the folder.""" 

311 

312 return PurePosixPath(str(stored).replace('\\', '/')).stem 

313 

314 

315def _paths_arg(args: dict[str, Any], *, least: int = 2) -> list[str]: 

316 raw = args.get('paths') 

317 if not isinstance(raw, list): 

318 raise ToolError('"paths" must be a list of playlist file paths.') 

319 paths = list(dict.fromkeys(_norm(p) for p in raw if _norm(p))) 

320 if len(paths) < least: 

321 raise ToolError(f'Give at least {least} different playlist paths.') 

322 if len(paths) > 20: 

323 raise ToolError('At most 20 playlists at a time.') 

324 return paths 

325 

326 

327def _reason_arg(args: dict[str, Any]) -> str: 

328 reason = str(args.get('reason') or '').strip() 

329 if not reason: 

330 raise ToolError( 

331 'Add a "reason": one or two sentences for the user saying why.' 

332 ) 

333 return reason[:MAX_REASON] 

334 

335 

336def _int_arg(args: dict[str, Any], name: str, default: int, top: int) -> int: 

337 try: 

338 value = int(args.get(name, default)) 

339 except (TypeError, ValueError): 

340 raise ToolError(f'"{name}" must be a whole number.') from None 

341 return max(0, min(value, top)) 

342 

343 

344def _http_error(exc: HTTPException) -> ToolError: 

345 detail = exc.detail if isinstance(exc.detail, dict) else {} 

346 code = detail.get('code') or str(exc.detail) 

347 hints = { 

348 'rescan_first': ( 

349 'The playlists section is out of date after a repair: call ' 

350 'run_health_check first.' 

351 ), 

352 'doctor_busy': ( 

353 'The Doctor is busy with another job: call get_job and try ' 

354 'again when it is done.' 

355 ), 

356 'm3u_not_found': f'No playlist file {detail.get("path")!r}.', 

357 'm3u_manual': ( 

358 f'{detail.get("path")!r} is a playlist the user made in the ' 

359 'Library; those are never merged.' 

360 ), 

361 'need_two': 'A group needs two different playlist files.', 

362 'playlists_differ': ( 

363 'These playlists share too few songs to be merged ' 

364 f'(overlap {detail.get("overlap")}, 0.8 needed).' 

365 ), 

366 'm3u_twice': f'{detail.get("path")!r} is in two groups.', 

367 } 

368 return ToolError(hints.get(code, f'Downtify refused: {code}')) 

369 

370 

371def _last_health() -> dict[str, Any]: 

372 entry = _doctor()._last.get('health') or {} 

373 return {'at': entry.get('at', ''), 'result': entry.get('result') or {}} 

374 

375 

376async def _infos() -> dict[str, Any]: 

377 dr = _doctor() 

378 infos = await asyncio.to_thread(dr._m3u_infos, dr._ctx()) 

379 return {i.path: i for i in infos} 

380 

381 

382async def _group(paths: list[str]): 

383 dr = _doctor() 

384 try: 

385 return await asyncio.to_thread(dr._group_for, paths) 

386 except HTTPException as exc: 

387 raise _http_error(exc) from None 

388 

389 

390def _job_view() -> Optional[dict[str, Any]]: 

391 job = _doctor()._public_job() 

392 if not job: 

393 return None 

394 view = { 

395 k: job.get(k) 

396 for k in ('id', 'kind', 'state', 'started_at', 'finished_at') 

397 if job.get(k) 

398 } 

399 view['progress'] = job.get('progress') 

400 if job.get('error'): 

401 view['error'] = job['error'] 

402 return view 

403 

404 

405async def tool_get_overview(_args: dict[str, Any]) -> dict[str, Any]: 

406 dr = _doctor() 

407 last = _last_health() 

408 playlists = last['result'].get('playlists') or {} 

409 return { 

410 'health_check_at': last['at'] or None, 

411 'playlist_files': playlists.get('m3u'), 

412 'duplicate_playlist_groups': len(playlists.get('groups') or []), 

413 'kept_apart_groups': playlists.get('kept_apart'), 

414 'out_of_date_sections': sorted(dr._stale), 

415 'doctor_job': _job_view(), 

416 'ai_can_apply': helper.can_apply, 

417 'waiting_suggestions': len(helper.waiting()), 

418 } 

419 

420 

421async def tool_run_health_check(args: dict[str, Any]) -> dict[str, Any]: 

422 dr = _doctor() 

423 wait = _int_arg(args, 'wait_seconds', 60, 300) 

424 if dr._busy(): 

425 raise ToolError( 

426 'The Doctor is busy with another job; call get_job and try ' 

427 'again when it is done.' 

428 ) 

429 try: 

430 job = await dr.doctor_scan() 

431 except HTTPException as exc: 

432 raise _http_error(exc) from None 

433 deadline = time.monotonic() + wait 

434 while time.monotonic() < deadline: 

435 if dr._job.get('id') != job['id'] or dr._job.get('state') != 'running': 

436 break 

437 await asyncio.sleep(1) 

438 view = _job_view() or {} 

439 if view.get('state') == 'running': 

440 return { 

441 'state': 'running', 

442 'progress': view.get('progress'), 

443 'note': 'Still checking; call get_job, then get_overview.', 

444 } 

445 overview = await tool_get_overview({}) 

446 overview['state'] = view.get('state') 

447 return overview 

448 

449 

450async def tool_get_job(_args: dict[str, Any]) -> dict[str, Any]: 

451 return {'doctor_job': _job_view()} 

452 

453 

454async def tool_list_duplicate_playlists( 

455 args: dict[str, Any], 

456) -> dict[str, Any]: 

457 last = _last_health() 

458 if not last['at']: 

459 raise ToolError('No health check yet: call run_health_check.') 

460 groups = (last['result'].get('playlists') or {}).get('groups') or [] 

461 offset = _int_arg(args, 'offset', 0, 100_000) 

462 limit = _int_arg(args, 'limit', 50, 200) or 50 

463 waiting = {p for s in helper.waiting() for p in s['paths']} 

464 page = [] 

465 for group in groups[offset : offset + limit]: 

466 members = group.get('members') or [] 

467 page.append({ 

468 'found_by': group.get('reason'), 

469 'paths': [m['path'] for m in members], 

470 'members': [ 

471 { 

472 'path': m['path'], 

473 'name': m.get('name'), 

474 'songs': m.get('songs'), 

475 'lines_in_file': m.get('lines'), 

476 'has_cover': m.get('cover'), 

477 } 

478 for m in members 

479 ], 

480 'keeper': group.get('keeper'), 

481 'songs_after_merge': group.get('songs_after'), 

482 'overlap': group.get('overlap'), 

483 'can_merge': bool(group.get('safe')), 

484 'already_suggested': any(m['path'] in waiting for m in members), 

485 }) 

486 return { 

487 'health_check_at': last['at'], 

488 'total_groups': len(groups), 

489 'offset': offset, 

490 'groups': page, 

491 'out_of_date': 'playlists' in _doctor()._stale, 

492 } 

493 

494 

495async def tool_list_playlists(args: dict[str, Any]) -> dict[str, Any]: 

496 query = str(args.get('query') or '').strip().casefold() 

497 offset = _int_arg(args, 'offset', 0, 100_000) 

498 limit = _int_arg(args, 'limit', 100, 500) or 100 

499 rows = (_last_health()['result'].get('playlists') or {}).get('list') 

500 if rows is None: 

501 rows = [i.as_dict() for i in (await _infos()).values()] 

502 if query: 

503 rows = [ 

504 r 

505 for r in rows 

506 if query in str(r.get('path', '')).casefold() 

507 or query in str(r.get('name', '')).casefold() 

508 ] 

509 rows = sorted(rows, key=lambda r: str(r.get('path', '')).casefold()) 

510 return { 

511 'total': len(rows), 

512 'offset': offset, 

513 'playlists': [ 

514 { 

515 'path': r.get('path'), 

516 'name': r.get('name'), 

517 'songs': r.get('songs'), 

518 'made_in_library': bool(r.get('manual')), 

519 'has_cover': r.get('cover'), 

520 } 

521 for r in rows[offset : offset + limit] 

522 ], 

523 } 

524 

525 

526async def tool_get_playlist(args: dict[str, Any]) -> dict[str, Any]: 

527 path = _norm(args.get('path')) 

528 if not path: 

529 raise ToolError('Give the playlist "path" (from list_playlists).') 

530 infos = await _infos() 

531 info = infos.get(path) 

532 if info is None: 

533 raise ToolError(f'No playlist file {path!r}.') 

534 offset = _int_arg(args, 'offset', 0, 100_000) 

535 limit = _int_arg(args, 'limit', PAGE, 1000) or PAGE 

536 songs = info.entries[offset : offset + limit] 

537 return { 

538 **info.as_dict(), 

539 'missing_lines': max(0, info.lines - len(info.entries)), 

540 'offset': offset, 

541 'songs': [{'song': _song_name(s), 'file': s} for s in songs], 

542 } 

543 

544 

545async def tool_compare_playlists(args: dict[str, Any]) -> dict[str, Any]: 

546 paths = _paths_arg(args) 

547 group = await _group(paths) 

548 data = group.as_dict() 

549 everyone = set.intersection(*(set(m.entries) for m in group.members)) 

550 members = [] 

551 for member in group.members: 

552 others = set().union( 

553 *(set(m.entries) for m in group.members if m is not member) 

554 ) 

555 only = [e for e in member.entries if e not in others] 

556 members.append({ 

557 'path': member.path, 

558 'name': member.name, 

559 'songs': len(member.entries), 

560 'has_cover': member.cover, 

561 'kept': member.path == group.keeper.path, 

562 'only_here_count': len(only), 

563 'only_here': [_song_name(e) for e in only[:PAGE]], 

564 }) 

565 return { 

566 'keeper': data['keeper'], 

567 'songs_after_merge': data['songs_after'], 

568 'overlap': data['overlap'], 

569 'can_merge': data['safe'], 

570 'in_all_of_them': len(everyone), 

571 'members': members, 

572 } 

573 

574 

575def _check_fresh() -> None: 

576 if 'playlists' in _doctor()._stale: 

577 raise ToolError( 

578 'The playlists section is out of date after a repair: call ' 

579 'run_health_check before suggesting more.' 

580 ) 

581 

582 

583async def _suggest(args: dict[str, Any], decision: str) -> dict[str, Any]: 

584 _check_fresh() 

585 paths = _paths_arg(args) 

586 reason = _reason_arg(args) 

587 group = await _group(paths) 

588 data = group.as_dict() 

589 # Say why these were grouped: the health check's own reason when 

590 # the assistant picked one of its groups, else that it chose them. 

591 picked = {m.path for m in group.members} 

592 found = (_last_health()['result'].get('playlists') or {}).get('groups') 

593 data['reason'] = next( 

594 ( 

595 g.get('reason') 

596 for g in found or [] 

597 if {m['path'] for m in g.get('members') or []} == picked 

598 ), 

599 'assistant', 

600 ) 

601 data['id'] = 'ai:' + data['keeper'] 

602 if decision == 'merge' and not data['safe']: 

603 raise ToolError( 

604 'These playlists share too few songs to be merged (overlap ' 

605 f'{data["overlap"]}, 0.8 needed). Suggest them as different ' 

606 'playlists, or tell the user.' 

607 ) 

608 try: 

609 entry = helper.add({ 

610 'kind': 'playlists', 

611 'decision': decision, 

612 'paths': [m.path for m in group.members], 

613 'reason': reason, 

614 'group': data, 

615 }) 

616 except ValueError as exc: 

617 code = str(exc) 

618 if code.startswith('already_suggested:'): 

619 raise ToolError( 

620 f'{code.split(":", 1)[1]!r} is already in a waiting ' 

621 'suggestion; withdraw that one first.' 

622 ) from None 

623 raise ToolError('Too many waiting suggestions.') from None 

624 return { 

625 'suggestion': entry['id'], 

626 'decision': decision, 

627 'keeper': data['keeper'] if decision == 'merge' else None, 

628 'note': ( 

629 'Shown in Downtify under Settings > Doctor > AI helper, ' 

630 'waiting for Apply.' 

631 ), 

632 } 

633 

634 

635async def tool_suggest_merge(args: dict[str, Any]) -> dict[str, Any]: 

636 return await _suggest(args, 'merge') 

637 

638 

639async def tool_suggest_different(args: dict[str, Any]) -> dict[str, Any]: 

640 return await _suggest(args, 'apart') 

641 

642 

643def _suggestion_view(s: dict[str, Any]) -> dict[str, Any]: 

644 group = s.get('group') or {} 

645 return { 

646 'id': s['id'], 

647 'section': s.get('kind'), 

648 'state': s['state'], 

649 'decision': s['decision'], 

650 'paths': s['paths'], 

651 'keeper': group.get('keeper') if s['decision'] == 'merge' else None, 

652 'reason': s['reason'], 

653 'error': s.get('error'), 

654 } 

655 

656 

657async def tool_list_suggestions(_args: dict[str, Any]) -> dict[str, Any]: 

658 refresh_states() 

659 return { 

660 'ai_can_apply': helper.can_apply, 

661 'suggestions': [ 

662 _suggestion_view(s) for s in helper.status()['suggestions'] 

663 ], 

664 } 

665 

666 

667async def tool_withdraw_suggestion(args: dict[str, Any]) -> dict[str, Any]: 

668 ids = args.get('ids') 

669 if not isinstance(ids, list) or not ids: 

670 raise ToolError('"ids" must list suggestion ids.') 

671 return {'withdrawn': helper.remove([str(i) for i in ids])} 

672 

673 

674async def tool_apply_suggestions(args: dict[str, Any]) -> dict[str, Any]: 

675 if not helper.can_apply: 

676 raise ToolError( 

677 'Applying from the chat is switched off in Downtify. Ask the ' 

678 'user to press Apply under Settings > Doctor > AI helper (or ' 

679 'to switch on "Let the assistant apply what you agree to in ' 

680 'the chat").' 

681 ) 

682 if args.get('user_agreed') is not True: 

683 raise ToolError( 

684 'Set "user_agreed": true only after the user agreed in this ' 

685 'chat to exactly these suggestions.' 

686 ) 

687 ids = args.get('ids') 

688 if not isinstance(ids, list) or not ids: 

689 raise ToolError('"ids" must list the suggestions to apply.') 

690 return await apply([str(i) for i in ids], by='assistant') 

691 

692 

693TOOLS: list[dict[str, Any]] = [ 

694 { 

695 'name': 'get_overview', 

696 'description': ( 

697 "Start here. When the Doctor's last health check ran, how " 

698 'many duplicate playlist groups it found, which sections are ' 

699 'out of date, the running Doctor job, whether you may apply ' 

700 'suggestions yourself, and how many wait.' 

701 ), 

702 'inputSchema': {'type': 'object', 'properties': {}}, 

703 'annotations': {'readOnlyHint': True}, 

704 'run': tool_get_overview, 

705 }, 

706 { 

707 'name': 'run_health_check', 

708 'description': ( 

709 "Run the Doctor's health check (changes nothing; it may hold " 

710 'new downloads for a moment). Waits up to wait_seconds for it ' 

711 'to finish.' 

712 ), 

713 'inputSchema': { 

714 'type': 'object', 

715 'properties': { 

716 'wait_seconds': { 

717 'type': 'integer', 

718 'minimum': 0, 

719 'maximum': 300, 

720 'default': 60, 

721 }, 

722 }, 

723 }, 

724 'annotations': {'readOnlyHint': True}, 

725 'run': tool_run_health_check, 

726 }, 

727 { 

728 'name': 'get_job', 

729 'description': "The Doctor's running or last job and its progress.", 

730 'inputSchema': {'type': 'object', 'properties': {}}, 

731 'annotations': {'readOnlyHint': True}, 

732 'run': tool_get_job, 

733 }, 

734 { 

735 'name': 'list_duplicate_playlists', 

736 'description': ( 

737 'Groups of playlist files the last health check thinks are ' 

738 'one playlist (found by the same name, or by mostly the same ' 

739 'songs), with song counts, the file a merge keeps, the ' 

740 'overlap and whether a merge is allowed.' 

741 ), 

742 'inputSchema': { 

743 'type': 'object', 

744 'properties': { 

745 'offset': {'type': 'integer', 'minimum': 0, 'default': 0}, 

746 'limit': { 

747 'type': 'integer', 

748 'minimum': 1, 

749 'maximum': 200, 

750 'default': 50, 

751 }, 

752 }, 

753 }, 

754 'annotations': {'readOnlyHint': True}, 

755 'run': tool_list_duplicate_playlists, 

756 }, 

757 { 

758 'name': 'list_playlists', 

759 'description': ( 

760 'Every playlist file, optionally filtered by a word in its ' 

761 'name or path. Use it to find playlists the check did not ' 

762 'pair.' 

763 ), 

764 'inputSchema': { 

765 'type': 'object', 

766 'properties': { 

767 'query': {'type': 'string'}, 

768 'offset': {'type': 'integer', 'minimum': 0, 'default': 0}, 

769 'limit': { 

770 'type': 'integer', 

771 'minimum': 1, 

772 'maximum': 500, 

773 'default': 100, 

774 }, 

775 }, 

776 }, 

777 'annotations': {'readOnlyHint': True}, 

778 'run': tool_list_playlists, 

779 }, 

780 { 

781 'name': 'get_playlist', 

782 'description': ( 

783 "One playlist file's songs (as 'Artist - Title' from the file " 

784 'names), in order, a page at a time.' 

785 ), 

786 'inputSchema': { 

787 'type': 'object', 

788 'properties': { 

789 'path': {'type': 'string'}, 

790 'offset': {'type': 'integer', 'minimum': 0, 'default': 0}, 

791 'limit': { 

792 'type': 'integer', 

793 'minimum': 1, 

794 'maximum': 1000, 

795 'default': PAGE, 

796 }, 

797 }, 

798 'required': ['path'], 

799 }, 

800 'annotations': {'readOnlyHint': True}, 

801 'run': tool_get_playlist, 

802 }, 

803 { 

804 'name': 'compare_playlists', 

805 'description': ( 

806 'Compare 2-20 playlist files song by song: how many songs ' 

807 'are in all of them, which are only in one, the file a merge ' 

808 'would keep and whether a merge is allowed.' 

809 ), 

810 'inputSchema': { 

811 'type': 'object', 

812 'properties': { 

813 'paths': { 

814 'type': 'array', 

815 'items': {'type': 'string'}, 

816 'minItems': 2, 

817 'maxItems': 20, 

818 }, 

819 }, 

820 'required': ['paths'], 

821 }, 

822 'annotations': {'readOnlyHint': True}, 

823 'run': tool_compare_playlists, 

824 }, 

825 { 

826 'name': 'suggest_merge', 

827 'description': ( 

828 'Suggest merging these playlist files into one (the keeper). ' 

829 'Changes nothing yet: the user sees it in Downtify and ' 

830 'presses Apply. "reason" is shown to the user.' 

831 ), 

832 'inputSchema': { 

833 'type': 'object', 

834 'properties': { 

835 'paths': { 

836 'type': 'array', 

837 'items': {'type': 'string'}, 

838 'minItems': 2, 

839 'maxItems': 20, 

840 }, 

841 'reason': {'type': 'string'}, 

842 }, 

843 'required': ['paths', 'reason'], 

844 }, 

845 'annotations': {'readOnlyHint': False, 'destructiveHint': False}, 

846 'run': tool_suggest_merge, 

847 }, 

848 { 

849 'name': 'suggest_different', 

850 'description': ( 

851 'Suggest marking these playlist files as different playlists ' 

852 'so the Doctor stops listing them together. Changes nothing ' 

853 'yet. "reason" is shown to the user.' 

854 ), 

855 'inputSchema': { 

856 'type': 'object', 

857 'properties': { 

858 'paths': { 

859 'type': 'array', 

860 'items': {'type': 'string'}, 

861 'minItems': 2, 

862 'maxItems': 20, 

863 }, 

864 'reason': {'type': 'string'}, 

865 }, 

866 'required': ['paths', 'reason'], 

867 }, 

868 'annotations': {'readOnlyHint': False, 'destructiveHint': False}, 

869 'run': tool_suggest_different, 

870 }, 

871 { 

872 'name': 'list_suggestions', 

873 'description': ( 

874 'Your suggestions and their state: waiting, applying, ' 

875 'applied, failed.' 

876 ), 

877 'inputSchema': {'type': 'object', 'properties': {}}, 

878 'annotations': {'readOnlyHint': True}, 

879 'run': tool_list_suggestions, 

880 }, 

881 { 

882 'name': 'withdraw_suggestion', 

883 'description': 'Take back waiting suggestions.', 

884 'inputSchema': { 

885 'type': 'object', 

886 'properties': { 

887 'ids': {'type': 'array', 'items': {'type': 'string'}}, 

888 }, 

889 'required': ['ids'], 

890 }, 

891 'annotations': {'readOnlyHint': False, 'destructiveHint': False}, 

892 'run': tool_withdraw_suggestion, 

893 }, 

894 { 

895 'name': 'apply_suggestions', 

896 'description': ( 

897 'Apply waiting suggestions now, as one Doctor job. Only ' 

898 'allowed when the user switched it on in Downtify ' 

899 '(get_overview: ai_can_apply) AND agreed in this chat to ' 

900 'exactly these suggestions.' 

901 ), 

902 'inputSchema': { 

903 'type': 'object', 

904 'properties': { 

905 'ids': {'type': 'array', 'items': {'type': 'string'}}, 

906 'user_agreed': {'type': 'boolean'}, 

907 }, 

908 'required': ['ids', 'user_agreed'], 

909 }, 

910 'annotations': {'readOnlyHint': False, 'destructiveHint': True}, 

911 'run': tool_apply_suggestions, 

912 }, 

913] 

914 

915_BY_NAME: dict[str, dict[str, Any]] = {t['name']: t for t in TOOLS} 

916 

917 

918def register(tools: list[dict[str, Any]]) -> None: 

919 """Add more tools (:mod:`downtify.doctor_ai_sections`).""" 

920 

921 for tool in tools: 

922 if tool['name'] not in _BY_NAME: 

923 TOOLS.append(tool) 

924 _BY_NAME[tool['name']] = tool 

925 

926 

927# --------------------------------------------------------------------------- 

928# Applying (from the page, or by the assistant when allowed) 

929# --------------------------------------------------------------------------- 

930 

931 

932#: One Doctor job to run for some suggestions: their ids, and a function 

933#: that starts the job (returns the job, or ``None`` when it is done at 

934#: once, like "different playlists"). 

935Step = tuple[list[str], Callable[[], Awaitable[Optional[dict[str, Any]]]]] 

936 

937#: How each kind of suggestion becomes Doctor jobs: ``kind`` -> 

938#: ``steps(chosen, user_id)``. :mod:`downtify.doctor_ai_sections` adds 

939#: the other Doctor sections. 

940APPLIERS: dict[str, Callable[[list[dict[str, Any]], int], list[Step]]] = {} 

941 

942#: How long a queued step waits for another Doctor job to end. 

943WAIT_IDLE = 30 * 60 

944 

945_runs: set[asyncio.Task[Any]] = set() 

946 

947 

948def _playlist_steps(chosen: list[dict[str, Any]], _user_id: int) -> list[Step]: 

949 dr = _doctor() 

950 payload = dr.PlaylistDecisions( 

951 merge=[s['paths'] for s in chosen if s['decision'] == 'merge'], 

952 apart=[s['paths'] for s in chosen if s['decision'] == 'apart'], 

953 ) 

954 

955 async def start() -> Optional[dict[str, Any]]: 

956 return (await dr.playlists_apply(payload)).get('job') 

957 

958 return [([s['id'] for s in chosen], start)] 

959 

960 

961APPLIERS['playlists'] = _playlist_steps 

962 

963 

964async def _wait_idle() -> None: 

965 dr = _doctor() 

966 deadline = time.monotonic() + WAIT_IDLE 

967 while dr._busy() and time.monotonic() < deadline: 

968 await asyncio.sleep(1) 

969 

970 

971async def _wait_job(job_id: str) -> None: 

972 dr = _doctor() 

973 while dr._job.get('id') == job_id and dr._job.get('state') == 'running': 

974 await asyncio.sleep(1) 

975 

976 

977async def _start_step(step: Step, by: str) -> Optional[str]: 

978 """Start one step; mark its suggestions. Returns the job's id.""" 

979 

980 ids, start = step 

981 try: 

982 job = await start() 

983 except HTTPException as exc: 

984 error = _http_error(exc) 

985 helper.update( 

986 ids, state='failed', error=str(error), error_code=_code(exc.detail) 

987 ) 

988 raise error from None 

989 if not job: 

990 helper.update(ids, state='applied', applied_by=by) 

991 return None 

992 helper.update(ids, state='applying', job=job.get('id', ''), applied_by=by) 

993 return job.get('id') 

994 

995 

996async def _run_rest(steps: list[Step], first_job: Optional[str], by: str): 

997 """The steps after the first, one Doctor job after the other.""" 

998 

999 if first_job: 

1000 await _wait_job(first_job) 

1001 refresh_states() 

1002 for step in steps: 

1003 await _wait_idle() 

1004 try: 

1005 job_id = await _start_step(step, by) 

1006 except ToolError: 

1007 continue 

1008 if job_id: 

1009 await _wait_job(job_id) 

1010 refresh_states() 

1011 

1012 

1013async def apply( 

1014 ids: list[str], *, by: str, user_id: int = 0 

1015) -> dict[str, Any]: 

1016 """Apply the waiting suggestions *ids*, all from one Doctor section. 

1017 

1018 The first job starts now (so a refusal, such as "check again first", 

1019 comes back at once); any further jobs (one per merged song) follow 

1020 one after the other in the background. 

1021 """ 

1022 

1023 chosen = helper.waiting(ids) 

1024 if not chosen: 

1025 raise ToolError('None of these suggestions is waiting.') 

1026 kinds = {s['kind'] for s in chosen} 

1027 if len(kinds) > 1: 

1028 raise ToolError( 

1029 'Apply one Doctor section at a time: a repair puts other ' 

1030 'sections out of date until they are checked again.' 

1031 ) 

1032 kind = kinds.pop() 

1033 steps = APPLIERS[kind](chosen, user_id or helper.user_id) 

1034 picked = [s['id'] for s in chosen] 

1035 helper.update(picked, state='queued', error=None) 

1036 try: 

1037 first_job = await _start_step(steps[0], by) 

1038 except ToolError: 

1039 later = [i for _ids, _start in steps[1:] for i in _ids] 

1040 helper.update(later, state='waiting') 

1041 raise 

1042 if len(steps) > 1 or first_job: 

1043 task = asyncio.get_running_loop().create_task( 

1044 _run_rest(steps[1:], first_job, by) 

1045 ) 

1046 _runs.add(task) 

1047 task.add_done_callback(_runs.discard) 

1048 logger.info( 

1049 'doctor ai: {} applied {} {} suggestion(s) in {} job(s)', 

1050 by, 

1051 len(picked), 

1052 kind, 

1053 len(steps), 

1054 ) 

1055 return { 

1056 'applied': len(picked), 

1057 'section': kind, 

1058 'merging': sum( 

1059 1 for s in chosen if s['decision'] in {'merge', 'keep'} 

1060 ), 

1061 'kept_apart': sum(1 for s in chosen if s['decision'] == 'apart'), 

1062 'jobs': len(steps), 

1063 'job': first_job, 

1064 'note': ( 

1065 'Running as Doctor job(s): see list_suggestions or get_job. ' 

1066 'Afterwards the sections this changed need a new health ' 

1067 'check before more repairs there.' 

1068 if first_job or len(steps) > 1 

1069 else 'Done.' 

1070 ), 

1071 } 

1072 

1073 

1074def _code(detail: Any) -> str: 

1075 """The Doctor's error code (the page has a message for each).""" 

1076 

1077 return str(detail.get('code') or '') if isinstance(detail, dict) else '' 

1078 

1079 

1080def refresh_states() -> None: 

1081 """Move 'applying' suggestions on once their Doctor job ended.""" 

1082 

1083 dr = _doctor() 

1084 job = dr._public_job() 

1085 if not job or job.get('state') == 'running': 

1086 return 

1087 for s in helper.status()['suggestions']: 

1088 if s['state'] == 'applying' and s.get('job') == job.get('id'): 

1089 if job.get('state') == 'done': 

1090 helper.update([s['id']], state='applied') 

1091 else: 

1092 error = job.get('error') or 'failed' 

1093 text = error 

1094 if isinstance(error, dict): 

1095 text = ' '.join( 

1096 str(error.get(k)) 

1097 for k in ('message', 'code', 'reason') 

1098 if error.get(k) 

1099 ) 

1100 helper.update( 

1101 [s['id']], 

1102 state='failed', 

1103 error=str(text), 

1104 error_code=_code(error), 

1105 ) 

1106 

1107 

1108# --------------------------------------------------------------------------- 

1109# JSON-RPC 

1110# --------------------------------------------------------------------------- 

1111 

1112 

1113def _error(id_: Any, code: int, message: str) -> dict[str, Any]: 

1114 return { 

1115 'jsonrpc': '2.0', 

1116 'id': id_, 

1117 'error': {'code': code, 'message': message}, 

1118 } 

1119 

1120 

1121def _result(id_: Any, result: dict[str, Any]) -> dict[str, Any]: 

1122 return {'jsonrpc': '2.0', 'id': id_, 'result': result} 

1123 

1124 

1125def _tool_list() -> list[dict[str, Any]]: 

1126 return [{k: v for k, v in t.items() if k != 'run'} for t in TOOLS] 

1127 

1128 

1129async def _call(params: dict[str, Any]) -> dict[str, Any]: 

1130 name = params.get('name') 

1131 tool = _BY_NAME.get(str(name)) 

1132 if tool is None: 

1133 raise KeyError(name) 

1134 args = params.get('arguments') or {} 

1135 if not isinstance(args, dict): 

1136 args = {} 

1137 run: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]] = tool['run'] 

1138 try: 

1139 data = await run(args) 

1140 except ToolError as exc: 

1141 return { 

1142 'content': [{'type': 'text', 'text': str(exc)}], 

1143 'isError': True, 

1144 } 

1145 except Exception as exc: 

1146 logger.opt(exception=True).warning('doctor ai: {} failed', name) 

1147 return { 

1148 'content': [ 

1149 {'type': 'text', 'text': f'{name} failed: {exc}'}, 

1150 ], 

1151 'isError': True, 

1152 } 

1153 return { 

1154 'content': [ 

1155 { 

1156 'type': 'text', 

1157 'text': json.dumps(data, ensure_ascii=False, indent=1), 

1158 }, 

1159 ], 

1160 'structuredContent': data, 

1161 'isError': False, 

1162 } 

1163 

1164 

1165async def handle(message: Any) -> Optional[dict[str, Any]]: 

1166 """Answer one JSON-RPC message (``None`` for a notification).""" 

1167 

1168 if not isinstance(message, dict) or message.get('jsonrpc') != '2.0': 

1169 return _error(None, INVALID_REQUEST, 'Not a JSON-RPC 2.0 message') 

1170 method = message.get('method') 

1171 id_ = message.get('id') 

1172 if 'id' not in message: 

1173 # Notifications (initialized, cancelled, ...) need no answer. 

1174 return None 

1175 if not isinstance(method, str): 

1176 # A response to something we never ask: nothing to do. 

1177 return None 

1178 params = message.get('params') or {} 

1179 if not isinstance(params, dict): 

1180 return _error(id_, INVALID_PARAMS, 'params must be an object') 

1181 if method == 'initialize': 

1182 asked = str(params.get('protocolVersion') or '') 

1183 version = asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0] 

1184 helper.set_client(params.get('clientInfo')) 

1185 return _result( 

1186 id_, 

1187 { 

1188 'protocolVersion': version, 

1189 'capabilities': {'tools': {'listChanged': False}}, 

1190 'serverInfo': { 

1191 'name': 'downtify-doctor', 

1192 'title': 'Downtify Doctor', 

1193 'version': __version__, 

1194 }, 

1195 'instructions': INSTRUCTIONS, 

1196 }, 

1197 ) 

1198 if method == 'ping': 

1199 return _result(id_, {}) 

1200 if method == 'tools/list': 

1201 return _result(id_, {'tools': _tool_list()}) 

1202 if method == 'tools/call': 

1203 try: 

1204 return _result(id_, await _call(params)) 

1205 except KeyError: 

1206 return _error( 

1207 id_, INVALID_PARAMS, f'Unknown tool: {params.get("name")}' 

1208 ) 

1209 return _error(id_, METHOD_NOT_FOUND, f'Method not found: {method}') 

1210 

1211 

1212def parse(body: bytes) -> Any: 

1213 try: 

1214 return json.loads(body.decode('utf-8')) 

1215 except (UnicodeDecodeError, json.JSONDecodeError): 

1216 raise ValueError('parse') from None