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
« 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.
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.
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.
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``.
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"""
27from __future__ import annotations
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
40from fastapi import HTTPException
41from loguru import logger
43from . import __version__, doctor_routes
45#: The helper stops by itself after this long without an AI request.
46IDLE_STOP = 2 * 60 * 60
48#: MCP protocol revisions this server answers to, newest first.
49PROTOCOL_VERSIONS = ('2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05')
51#: At most this many suggestions wait at once.
52MAX_SUGGESTIONS = 500
54#: Longest reason kept from the assistant.
55MAX_REASON = 2000
57#: Songs listed per page by ``get_playlist`` / per side by ``compare``.
58PAGE = 200
60# JSON-RPC error codes.
61PARSE_ERROR = -32700
62INVALID_REQUEST = -32600
63METHOD_NOT_FOUND = -32601
64INVALID_PARAMS = -32602
67def _now_iso() -> str:
68 return datetime.now(timezone.utc).isoformat()
71class Helper:
72 """Whether the helper runs, its key, and the assistant's suggestions."""
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]] = []
86 # -- running ---------------------------------------------------------
88 @property
89 def running(self) -> bool:
90 with self._lock:
91 return self._running_locked()
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
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."""
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
116 def stop(self) -> None:
117 with self._lock:
118 self._stop_locked()
120 def _stop_locked(self) -> None:
121 self.token = ''
122 self.started_at = ''
123 self.client = ''
124 self.can_apply = False
126 def check(self, header: str) -> bool:
127 """Whether an ``Authorization`` header carries the current key;
128 a good one counts as activity."""
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
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()
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 }
166 # -- suggestions -----------------------------------------------------
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)
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 ]
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)
204 def remove(self, ids: list[str]) -> int:
205 """Drop waiting suggestions (dismissed or withdrawn)."""
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)
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)
227helper = Helper()
230# ---------------------------------------------------------------------------
231# What the assistant is told
232# ---------------------------------------------------------------------------
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:
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.
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.
285Paths are relative to the downloads folder. Keep answers short and
286readable: names, counts and lengths, not raw JSON.
287"""
290# ---------------------------------------------------------------------------
291# Tools
292# ---------------------------------------------------------------------------
295class ToolError(Exception):
296 """A tool call the assistant should correct (shown to it as text)."""
299def _doctor():
300 """The Doctor's routes module (a function, so tests can swap it)."""
302 return doctor_routes
305def _norm(path: Any) -> str:
306 return str(path or '').strip().replace('\\', '/').lstrip('/')
309def _song_name(stored: str) -> str:
310 """``Artist - Title`` as the file name says, without the folder."""
312 return PurePosixPath(str(stored).replace('\\', '/')).stem
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
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]
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))
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}'))
371def _last_health() -> dict[str, Any]:
372 entry = _doctor()._last.get('health') or {}
373 return {'at': entry.get('at', ''), 'result': entry.get('result') or {}}
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}
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
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
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 }
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
450async def tool_get_job(_args: dict[str, Any]) -> dict[str, Any]:
451 return {'doctor_job': _job_view()}
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 }
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 }
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 }
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 }
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 )
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 }
635async def tool_suggest_merge(args: dict[str, Any]) -> dict[str, Any]:
636 return await _suggest(args, 'merge')
639async def tool_suggest_different(args: dict[str, Any]) -> dict[str, Any]:
640 return await _suggest(args, 'apart')
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 }
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 }
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])}
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')
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]
915_BY_NAME: dict[str, dict[str, Any]] = {t['name']: t for t in TOOLS}
918def register(tools: list[dict[str, Any]]) -> None:
919 """Add more tools (:mod:`downtify.doctor_ai_sections`)."""
921 for tool in tools:
922 if tool['name'] not in _BY_NAME:
923 TOOLS.append(tool)
924 _BY_NAME[tool['name']] = tool
927# ---------------------------------------------------------------------------
928# Applying (from the page, or by the assistant when allowed)
929# ---------------------------------------------------------------------------
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]]]]]
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]]] = {}
942#: How long a queued step waits for another Doctor job to end.
943WAIT_IDLE = 30 * 60
945_runs: set[asyncio.Task[Any]] = set()
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 )
955 async def start() -> Optional[dict[str, Any]]:
956 return (await dr.playlists_apply(payload)).get('job')
958 return [([s['id'] for s in chosen], start)]
961APPLIERS['playlists'] = _playlist_steps
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)
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)
977async def _start_step(step: Step, by: str) -> Optional[str]:
978 """Start one step; mark its suggestions. Returns the job's id."""
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')
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."""
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()
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.
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 """
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 }
1074def _code(detail: Any) -> str:
1075 """The Doctor's error code (the page has a message for each)."""
1077 return str(detail.get('code') or '') if isinstance(detail, dict) else ''
1080def refresh_states() -> None:
1081 """Move 'applying' suggestions on once their Doctor job ended."""
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 )
1108# ---------------------------------------------------------------------------
1109# JSON-RPC
1110# ---------------------------------------------------------------------------
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 }
1121def _result(id_: Any, result: dict[str, Any]) -> dict[str, Any]:
1122 return {'jsonrpc': '2.0', 'id': id_, 'result': result}
1125def _tool_list() -> list[dict[str, Any]]:
1126 return [{k: v for k, v in t.items() if k != 'run'} for t in TOOLS]
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 }
1165async def handle(message: Any) -> Optional[dict[str, Any]]:
1166 """Answer one JSON-RPC message (``None`` for a notification)."""
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}')
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