name: analyze_release

summary: >
  One-shot analyzer that parses a release name, detects its media type
  from the folder layout, and enriches the result with ffprobe data.

description: |
  Combines three steps in a single call so the agent gets a complete
  picture before routing:
    1. parse_release(release_name) — extracts title, year, season,
       episode, quality, source, codec, group, languages, audio info,
       HDR, edition, site tag.
    2. detect_media_type(parsed, path) — uses the on-disk layout
       (single file vs. folder, presence of S01 dirs, episode count)
       to choose: movie / tv_episode / tv_season / tv_complete /
       other / unknown.
    3. ffprobe enrichment — when the media type is recognised, runs
       ffprobe on the first video file found and fills in audio
       codec/channels, bit depth, HDR format. Sets probe_used=true.

when_to_use: |
  As the very first step of any organize workflow, right after
  list_folder, on each release the user wants to handle. The output
  drives which resolve_*_destination to call next.

when_not_to_use: |
  - When you only need codec/audio info on a specific video file:
    use probe_media (no parsing, no media-type detection).
  - For releases the user has already analyzed earlier in the same
    workflow — the parse is deterministic, no need to re-run.

next_steps: |
  - media_type == movie       → resolve_movie_destination
  - media_type == tv_season   → resolve_season_destination
  - media_type == tv_episode  → resolve_episode_destination
  - media_type == tv_complete → resolve_series_destination
  - media_type in (other, unknown) → ask the user what to do; do not
    auto-route.

cache:
  key: source_path

parameters:
  release_name:
    description: Raw release folder or file name as it appears on disk.
    why_needed: |
      Source of all the parsed tokens (quality, codec, group, ...).
      Don't sanitise it — the parser relies on the exact spelling.
    example: Breaking.Bad.S01.1080p.BluRay.x265-GROUP

  source_path:
    description: Absolute path to the release folder or file on disk.
    why_needed: |
      Required for layout-based media-type detection and for ffprobe
      to find a video file inside the release.
    example: /downloads/Breaking.Bad.S01.1080p.BluRay.x265-GROUP

returns:
  ok:
    description: Release analyzed.
    fields:
      status: "'ok'"
      media_type: "One of: movie, tv_episode, tv_season, tv_complete, other, unknown."
      parse_path: "Which parser branch was taken (debug)."
      title: Parsed title.
      year: Parsed year (int) or null.
      season: Season number (int) or null.
      episode: Episode number (int) or null.
      episode_end: Range end episode (multi-episode releases) or null.
      quality: Resolution token (e.g. 1080p, 2160p).
      source: Source token (BluRay, WEB-DL, ...).
      codec: Video codec token (x264, x265, ...).
      group: Release group name or null.
      languages: List of detected language tokens.
      audio_codec: Audio codec from ffprobe (when probe_used=true).
      audio_channels: Audio channel count from ffprobe.
      bit_depth: Bit depth from ffprobe.
      hdr_format: HDR format from ffprobe (HDR10, DV, ...) or null.
      edition: Edition tag (Extended, Director's Cut, ...) or null.
      site_tag: Source-site tag if present.
      is_season_pack: True when the folder contains a full season.
      probe_used: True when ffprobe successfully enriched the result.