"""Plan generator for creating execution plans from parsed identities. This module generates structured execution plans that specify how video files should be organized based on their parsed identities and configuration templates. """ import json import re import uuid from datetime import datetime from pathlib import Path from typing import Optional, Union from vlm.config import Config from vlm.duplicate_resolve import choose_keep_index from vlm.utils import ensure_utc, is_within_root, sanitize_path_component, utc_now from vlm.models import ( ExecutionPlan, FileOperation, MovieIdentity, SeriesIdentity, VideoFile, ) QUARANTINE_REASON_DUPLICATE = "重复项（已按外部评分保留一条）" QUARANTINE_REASON_DUPLICATE_FALLBACK_QUALITY = "重复项（外部评分缺失/并列，按画质回退保留一条）" QUARANTINE_REASON_DUPLICATE_BY_QUALITY = "重复项（已按画质保留最优）" QUARANTINE_REASON_DUPLICATE_BY_REPUTATION_QUALITY_TIME = "重复项（按外部评分>画质>时间保留一条）" NO_OP_REASON_SAMPLE_EXCLUDED = "Sample file excluded by plan include_sample_files=false" NO_OP_REASON_SEASON_OUT_OF_RANGE = "Series needs manual review (season exceeds configured threshold)" NO_OP_REASON_EPISODE_OUT_OF_RANGE = "Series needs manual review (episode exceeds configured threshold)" def _is_sample_path(path: Path) -> bool: """Return True if path appears to be a sample clip.""" parts = [part.casefold() for part in path.parts] if "sample" in parts: return True stem = path.stem.casefold() return bool(re.search(r"(^|[\s._-])sample($|[\s._-])", stem)) def _analyze_directory_impact(operations: list[FileOperation]) -> dict: """Analyze which directories will be emptied by the plan.""" # Get all source directories that have files being moved/renamed source_dirs = set() moved_files = set() for operation in operations: if operation.operation_type in ("move", "rename"): source_dirs.add(operation.source_path.parent) moved_files.add(operation.source_path) emptied_dirs = [] for dir_path in source_dirs: # Only analyze directories that actually exist if not dir_path.exists(): continue # Count files that will remain in this directory after operations remaining_count = 0 try: for item in dir_path.iterdir(): if item.is_file() and item not in moved_files: remaining_count += 1 except (OSError, PermissionError): # If we can't read the directory, skip analysis continue # If no files will remain, this directory will be emptied if remaining_count == 0: emptied_dirs.append(dir_path) return { "emptied_directories": emptied_dirs, "warning_required": len(emptied_dirs) > 0 } def generate_plan( identities: list[tuple[VideoFile, Union[MovieIdentity, SeriesIdentity, None]]], config: Config, analysis_data: Optional[dict] = None, ignored_paths: Optional[set[str]] = None, ) -> ExecutionPlan: """Generate an execution plan from parsed identities; optionally apply analysis duplicates. When analysis_data is provided and duplicate_keep is not "manual", duplicate groups are resolved (one kept, rest quarantined) according to config.duplicate_keep. If ignored_paths is provided, files in that set will generate no-op operations. """ operations = [] for video_file, identity in identities: # Check if file is ignored in state if ignored_paths and str(video_file.path) in ignored_paths: operation = FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="User marked as ignored in state", has_conflict=False, conflict_reason=None ) else: operation = _create_operation(video_file, identity, config) operations.append(operation) metadata: dict = {} if analysis_data is not None: metadata["analysis_source"] = analysis_data.get("metadata", {}).get("source_identities", "") metadata["duplicate_groups_considered"] = len(analysis_data.get("duplicates", [])) metadata["completeness_seasons_with_gaps"] = len(analysis_data.get("completeness", [])) if config.duplicate_keep != "manual": path_to_index = {str(vf.path): i for i, (vf, _) in enumerate(identities)} for dup in analysis_data.get("duplicates", []): paths = dup.get("files", []) indices = [path_to_index[p] for p in paths if p in path_to_index] path_to_qc = {qc.get("path"): qc for qc in dup.get("quality_comparison", [])} items = [] valid_indices = [] for i in indices: identity = identities[i][1] if identity is not None and isinstance( identity, (MovieIdentity, SeriesIdentity) ): if not config.plan_include_sample_files and _is_sample_path(identities[i][0].path): # Keep sample files out of duplicate keep/quarantine competition by default. continue items.append((identities[i][0].path, identity)) valid_indices.append(i) if not items: continue quality_list = [ path_to_qc.get(str(p), {}) for p, _ in items ] keep_idx = choose_keep_index( items, config.duplicate_keep, quality_comparison=quality_list ) if keep_idx is None: continue keep_identity_index = valid_indices[keep_idx] quarantine_indices = set(valid_indices) - {keep_identity_index} reason = _select_duplicate_quarantine_reason( config.duplicate_keep, [identity for _, identity in items], ) for i in quarantine_indices: vf = identities[i][0] operations[i] = FileOperation( operation_type="quarantine", source_path=vf.path, destination_path=None, reason=reason, has_conflict=False, conflict_reason=None, ) # Analyze directory impact and add preservation operations directory_analysis = _analyze_directory_impact(operations) if directory_analysis["warning_required"]: # Add directory preservation operations for emptied directories for emptied_dir in directory_analysis["emptied_directories"]: operations.append(FileOperation( operation_type="preserve-directory", source_path=emptied_dir, destination_path=None, reason=f"Preserve empty source directory: {emptied_dir.name}", has_conflict=False, conflict_reason=None )) summary = _generate_summary(operations) summary_by_reason = _generate_summary_by_reason(operations) human_summary = _generate_human_summary(operations, summary, summary_by_reason, metadata) # Add directory warnings to metadata if directory_analysis["warning_required"]: metadata["emptied_directories"] = [str(d) for d in directory_analysis["emptied_directories"]] metadata["directory_warning"] = True return ExecutionPlan( plan_id=str(uuid.uuid4()), created_at=utc_now(), operations=operations, summary=summary, summary_by_reason=summary_by_reason, human_summary=human_summary, metadata=metadata, ) def _create_operation( video_file: VideoFile, identity: Union[MovieIdentity, SeriesIdentity, None], config: Config ) -> FileOperation: """Create a file operation for a single video file. Args: video_file: The video file to create an operation for identity: Parsed identity (MovieIdentity, SeriesIdentity, or None) config: Configuration with templates Returns: FileOperation specifying what to do with the file """ if not config.plan_include_sample_files and _is_sample_path(video_file.path): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason=NO_OP_REASON_SAMPLE_EXCLUDED, has_conflict=False, conflict_reason=None ) # Handle anime category - generate no-op (v1 constraint) if video_file.category == "anime": return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Anime files not organized in v1", has_conflict=False, conflict_reason=None ) # Handle other category - generate no-op (v1 constraint) if video_file.category == "other": return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Other files not organized in v1", has_conflict=False, conflict_reason=None ) # Handle files without identity - generate no-op if identity is None: return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="No identity parsed", has_conflict=False, conflict_reason=None ) # Handle movie identity if isinstance(identity, MovieIdentity): return _create_movie_operation(video_file, identity, config) # Handle series identity if isinstance(identity, SeriesIdentity): return _create_series_operation(video_file, identity, config) # Fallback - should not reach here return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Unknown identity type", has_conflict=False, conflict_reason=None ) def _create_movie_operation( video_file: VideoFile, identity: MovieIdentity, config: Config ) -> FileOperation: """Create operation for a movie file. Args: video_file: The movie file identity: Parsed movie identity config: Configuration with templates Returns: FileOperation for organizing the movie """ # Explicitly blocked by manual review workflow. if identity.review_status == "rejected": return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Movie rejected during manual review", has_conflict=False, conflict_reason=None ) # If movie needs review (no year or low-confidence enrichment), generate no-op if identity.needs_review or identity.year is None: return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Movie needs manual review (no year found)", has_conflict=False, conflict_reason=None ) safe_title = sanitize_path_component(identity.title, fallback="untitled") # Apply movie directory template target_dir = config.movie_template.format( title=safe_title, year=identity.year ) # Get file extension ext = video_file.path.suffix # Apply movie filename template target_filename = config.movie_filename_template.format( title=safe_title, year=identity.year, ext=ext ) # Construct full destination path destination = config.library_root / target_dir / target_filename if not is_within_root(destination, config.library_root): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason=f"Unsafe destination outside library root: {destination}", has_conflict=False, conflict_reason=None ) # Check if source and destination are the same if video_file.path.resolve() == destination.resolve(): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="File already at target location", has_conflict=False, conflict_reason=None ) # Determine operation type (move or rename) if video_file.path.parent == destination.parent: operation_type = "rename" else: operation_type = "move" # Check for conflicts - destination file already exists has_conflict = destination.exists() conflict_reason = None if has_conflict: conflict_reason = f"Destination file already exists: {destination}" return FileOperation( operation_type=operation_type, source_path=video_file.path, destination_path=destination, reason=f"Organize movie: {identity.title} ({identity.year})", has_conflict=has_conflict, conflict_reason=conflict_reason ) def _create_series_operation( video_file: VideoFile, identity: SeriesIdentity, config: Config ) -> FileOperation: """Create operation for a series file. Args: video_file: The series file identity: Parsed series identity config: Configuration with templates Returns: FileOperation for organizing the series episode """ # Explicitly blocked by manual review workflow. if identity.review_status == "rejected": return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Series rejected during manual review", has_conflict=False, conflict_reason=None ) # If series needs review (no season or no episodes), generate no-op if identity.needs_review or identity.season is None or len(identity.episodes) == 0: return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="Series needs manual review (no season/episode found)", has_conflict=False, conflict_reason=None ) if identity.season > config.plan_max_season: return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason=NO_OP_REASON_SEASON_OUT_OF_RANGE, has_conflict=False, conflict_reason=None ) if any(ep > config.plan_max_episode for ep in identity.episodes): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason=NO_OP_REASON_EPISODE_OUT_OF_RANGE, has_conflict=False, conflict_reason=None ) safe_title = sanitize_path_component(identity.title, fallback="untitled") # Apply series directory template target_dir = config.series_template.format( title=safe_title, season=identity.season ) # Get file extension ext = video_file.path.suffix # Apply series filename template # For multi-episode files, use the first episode number target_filename = config.series_filename_template.format( season=identity.season, episode=identity.episodes[0], ext=ext ) # Construct full destination path destination = config.library_root / target_dir / target_filename if not is_within_root(destination, config.library_root): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason=f"Unsafe destination outside library root: {destination}", has_conflict=False, conflict_reason=None ) # Check if source and destination are the same if video_file.path.resolve() == destination.resolve(): return FileOperation( operation_type="no-op", source_path=video_file.path, destination_path=None, reason="File already at target location", has_conflict=False, conflict_reason=None ) # Determine operation type (move or rename) if video_file.path.parent == destination.parent: operation_type = "rename" else: operation_type = "move" # Check for conflicts - destination file already exists has_conflict = destination.exists() conflict_reason = None if has_conflict: conflict_reason = f"Destination file already exists: {destination}" return FileOperation( operation_type=operation_type, source_path=video_file.path, destination_path=destination, reason=f"Organize series: {identity.title} S{identity.season:02d}E{identity.episodes[0]:02d}", has_conflict=has_conflict, conflict_reason=conflict_reason ) def _generate_summary(operations: list[FileOperation]) -> dict: """Generate summary statistics for operations. Args: operations: List of file operations Returns: Dictionary with operation counts by type """ summary = { "total": len(operations), "move": 0, "rename": 0, "quarantine": 0, "no-op": 0, "preserve-directory": 0 } for operation in operations: op_type = operation.operation_type if op_type in summary: summary[op_type] += 1 return summary def _generate_summary_by_reason(operations: list[FileOperation]) -> dict[str, int]: """Aggregate operation counts by reason string.""" out: dict[str, int] = {} for op in operations: r = op.reason out[r] = out.get(r, 0) + 1 return out def _generate_human_summary( operations: list[FileOperation], summary: dict, summary_by_reason: dict[str, int], metadata: dict, ) -> str: """Build a short Chinese narrative summary of the plan.""" total = summary.get("total", len(operations)) move = summary.get("move", 0) rename = summary.get("rename", 0) quarantine = summary.get("quarantine", 0) noop = summary.get("no-op", 0) conflicts = sum(1 for op in operations if op.has_conflict) parts = [ f"本计划共 {total} 条操作：move {move}，rename {rename}，quarantine {quarantine}，no-op {noop}。" ] if summary_by_reason: reason_lines = [f" - {r}: {c} 条" for r, c in sorted(summary_by_reason.items(), key=lambda x: -x[1])[:10]] parts.append("原因分布：") parts.extend(reason_lines) if conflicts > 0: parts.append(f"冲突 {conflicts} 条。") if metadata: dup = metadata.get("duplicate_groups_considered", 0) gaps = metadata.get("completeness_seasons_with_gaps", 0) if dup or gaps: parts.append(f"依据 analysis：重复组 {dup} 个；剧集缺口 {gaps} 季。") quarantine_lines = _build_quarantine_recommendation_lines(operations) if quarantine_lines: parts.append("删除建议（仅隔离建议，执行删除前请人工复核）：") parts.extend(quarantine_lines) return "\n".join(parts) def _select_duplicate_quarantine_reason( strategy: str, identities: list[Union[MovieIdentity, SeriesIdentity]], ) -> str: """Choose a user-facing reason string for duplicate quarantine.""" if strategy == "by_quality": return QUARANTINE_REASON_DUPLICATE_BY_QUALITY if strategy == "by_reputation_quality_time": return QUARANTINE_REASON_DUPLICATE_BY_REPUTATION_QUALITY_TIME if strategy == "by_reputation": rep_values = [i.reputation_score for i in identities if i.reputation_score is not None] if len(rep_values) <= 1: return QUARANTINE_REASON_DUPLICATE_FALLBACK_QUALITY return QUARANTINE_REASON_DUPLICATE return QUARANTINE_REASON_DUPLICATE def _build_quarantine_recommendation_lines(operations: list[FileOperation], limit: int = 20) -> list[str]: """Build human-readable quarantine recommendations with reasons.""" quarantines = [op for op in operations if op.operation_type == "quarantine"] if not quarantines: return [] lines: list[str] = [] for op in quarantines[:limit]: risk_tags = [] name_l = op.source_path.name.casefold() if any(tok in name_l for tok in ("disc1", "disc2", "part.", " part ", "cd1", "cd2")): risk_tags.append("疑似多碟/分段文件，建议勿直接删除") if "评分缺失/并列" in op.reason: risk_tags.append("评分依据不足，已回退画质规则") risk_text = f"（{'; '.join(risk_tags)}）" if risk_tags else "" lines.append(f" - {op.source_path.name} -> {op.reason}{risk_text}") if len(quarantines) > limit: lines.append(f" - 其余 {len(quarantines) - limit} 条请查看 plan.json 的 quarantine 操作。") return lines def save_plan(plan: ExecutionPlan, output_path: Path) -> None: """Save execution plan to JSON file. Serializes the execution plan to a human-readable and editable JSON format. Includes plan_id, created_at timestamp, operations list, and summary. Args: plan: ExecutionPlan to save output_path: Path where the JSON file should be saved """ # Convert ExecutionPlan to dictionary plan_dict = { "vlm_schema_version": "1.0", "plan_id": plan.plan_id, "created_at": plan.created_at.isoformat(), "operations": [ { "operation_type": op.operation_type, "source_path": str(op.source_path), "destination_path": str(op.destination_path) if op.destination_path else None, "reason": op.reason, "has_conflict": op.has_conflict, "conflict_reason": op.conflict_reason } for op in plan.operations ], "summary": plan.summary, "summary_by_reason": plan.summary_by_reason, "human_summary": plan.human_summary, "metadata": plan.metadata, } # Write to JSON file with indentation for human readability with open(output_path, 'w', encoding='utf-8') as f: json.dump(plan_dict, f, indent=2, ensure_ascii=False) def load_plan(input_path: Path) -> ExecutionPlan: """Load execution plan from JSON file. Deserializes an execution plan from JSON format, reconstructing all data structures including Path and datetime objects. Args: input_path: Path to the JSON file to load Returns: ExecutionPlan reconstructed from JSON Raises: FileNotFoundError: If the input file does not exist json.JSONDecodeError: If the file contains invalid JSON KeyError: If required fields are missing from the JSON """ with open(input_path, 'r', encoding='utf-8') as f: plan_dict = json.load(f) # Reconstruct FileOperation objects operations = [ FileOperation( operation_type=op["operation_type"], source_path=Path(op["source_path"]), destination_path=Path(op["destination_path"]) if op["destination_path"] else None, reason=op["reason"], has_conflict=op["has_conflict"], conflict_reason=op.get("conflict_reason") ) for op in plan_dict["operations"] ] # Reconstruct ExecutionPlan (normalize naive datetime to UTC for backward compatibility) created_at = ensure_utc(datetime.fromisoformat(plan_dict["created_at"])) return ExecutionPlan( plan_id=plan_dict["plan_id"], created_at=created_at, operations=operations, summary=plan_dict["summary"], summary_by_reason=plan_dict.get("summary_by_reason", {}), human_summary=plan_dict.get("human_summary", ""), metadata=plan_dict.get("metadata", {}), )