Organize Files

Use moviepilot_api for every MoviePilot business operation. Retired file, recognition, transfer, and history tools are not available.

Workflow

1. Establish scope. If the user provides a path, use it. If they identify a downloader task, use downloader-operation and its fixed scripts/mp-downloader.py helper to discover the instance and call tasks.list. If they only name a configured root, call storage.settings. Use storage.list to inspect the selected directory. Do not process a broad shared root without an explicit, bounded scope.
2. Classify files into movie, TV, one music recording, one complete album, subtitle/sidecar, or unrelated content. Do not group unrelated media merely because they share a directory.
3. Call media.recognize with the representative title or path. If uncertain, call media.search; if several exact candidates remain, use ask_user_choice. Never invent or translate an ID.
4. Preserve the exact media_source + media_id. For TV, verify season detail with media.detail when numbering is ambiguous. For music, a recording is one track, an album is one multi-track directory, and an artist is browse-only.
5. When duplicate risk matters, call library.exists. If an existing transfer record affects reorganization, inspect transfer.history.
6. Before a state-changing transfer, summarize the source, target identity, media type, season/music entity, storage, and mode. Continue only when the user's request already authorizes that exact action or after confirmation.
7. Call transfer.file once per verified unit. For an album, transfer the album directory once only after its supported audio-file count is consistent with the selected album detail.
8. If requested, call media.scrape after a successful transfer. Report actual tag, cover, and lyrics counts; never assume all lyrics were found.

Structured Calls