francwa
5107cb32c0
Add a derived 'recommended_action' property on InspectedResult that collapses the orchestrator's go / wait / skip decision into one value: - 'skip' → no main_video, or media_type == 'other' - 'ask_user' → media_type == 'unknown', or road == 'path_of_pain' - 'process' → confident parse with a main video on disk The ordering is part of the contract (skip > ask_user > process) — documented in the property docstring. Until now every consumer (workflows, the agent, the orchestrator sketch) had to re-derive this from the road / media_type / main_video triple, with subtle drift between sites. One place, one rule. Exposed through the analyze_release tool so the LLM can route on it. Spec YAML updated to describe the new field. Suite: 1083 passed (+6 new tests in tests/application/test_inspect.py covering the four branches and the precedence rules).
86 lines
3.9 KiB
YAML
86 lines
3.9 KiB
YAML
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.
|
||
confidence: Parser confidence score, 0–100 (higher = more reliable).
|
||
road: "Parser road: 'easy' (group schema matched), 'shitty' (heuristic but acceptable), or 'path_of_pain' (low confidence — ask the user before auto-routing)."
|
||
recommended_action: "Orchestrator hint: 'process' (go straight to resolve_*_destination), 'ask_user' (media_type unknown or road=path_of_pain — confirm with the user first), or 'skip' (no main video, or media_type=other — nothing to organize)."
|