dl-organizer/GEMINI.md

GEMINI.md

Documentation Status

• Synced with the post-refactor baseline on 2026-04-07 (source of truth: CHANGELOG.md).

This document provides a comprehensive overview of the Video Library Manager (VLM) project, intended to be used as instructional context for Gemini.

Project Overview

The Video Library Manager (VLM) is a Python-based CLI tool designed for managing personal video collections. It emphasizes a "safety-first" and "human-in-the-loop" approach, ensuring that no file operations are performed without explicit user confirmation and that all actions are reversible through a rollback mechanism.

Core Functionality:

• Scanning & Parsing: Discovers video files, extracts metadata. Proactively detects ffprobe for video properties with graceful fallback to file-level metadata. Parses filenames for titles, years, seasons, and episodes, with specific support for Anime-style hyphenated numbering and release group stripping.
• Metadata Enrichment: Augments local data with information from TMDB, including bilingual titles and reputation scores. It uses a local SQLite cache to improve performance.
• Analysis: Detects duplicate files (with quality comparisons) and identifies gaps in TV series episodes.
• Planning & Execution: Generates a reviewable JSON-based execution plan for file operations (move, rename, quarantine), validates move/rename sources and destinations against library_root during execution, and keeps execution failures isolated per operation.
• Plan Review Cycle: Exports high-risk operations to CSV for manual confirmation (review-plan), offers an optional Textual TUI via review-plan --tui, and synchronizes user decisions back to the master plan (apply-review).
• Quarantine Management: Safely isolates files for review, with full support for listing and restoration.
• Reporting: Creates reports for inventory, duplicate files, and series completeness.
• State Management: Tracks the status of files throughout the organization workflow.

Technologies:

• Language: Python 3.10+
• CLI Framework: Click
• Configuration: YAML
• Dependencies: pyyaml, click
• Development: pytest for testing, hypothesis for property-based testing.
• Package Management: uv is mentioned in the documentation.

Architecture:

The project follows a modular structure located in the src/vlm directory.

• cli.py: The main entry point for the CLI, using Click.
• commands/*.py: Implementation of the individual CLI commands (scan, parse, enrich, analyze, plan, execute/rollback).
• scanner.py, parser.py, enrichment.py, analysis.py, planner.py, executor.py: Core logic for the different stages of the workflow.
• io.py: Unified I/O layer for JSON and CSV handling, including validated typed plan loading.
• cache.py: Local SQLite cache for TMDB metadata.
• context.py: CLI context and state management for command execution.
• duplicate_resolve.py: Logic for resolving duplicate files with explicit failure on unsupported or ambiguous inputs.
• logging_config.py: Centralized logging configuration.
• plan_review.py: Risk analysis and manual review generation for execution plans.
• quarantine.py: Management of quarantined files (listing, adding, restoring).
• reports.py: Generation of inventory, completeness, and duplicate reports.
• state.py: File status tracking and persistence (reviewed, ignored, planned, etc.).
• providers/tmdb.py: Client for interacting with the TMDB API.
• models.py: Defines the data structures used throughout the application.
• config.py: Manages application configuration from a YAML file.
• utils.py: General utility functions (formatting, path handling).

Building and Running

The project uses uv for dependency management.

Installation:

• Install dependencies: uv pip install -e .
• Install development dependencies: uv pip install -e ".[dev]"
• Install the optional Textual review UI: uv pip install -e ".[tui]"

Running the application:

The main entry point is the vlm command.

• Initialize configuration: uv run vlm config init
• Scan the library: uv run vlm scan
• Parse filenames: uv run vlm parse
• Enrich metadata: uv run vlm enrich
• Analyze the library: uv run vlm analyze
• Generate a plan: uv run vlm plan
• Review a plan: uv run vlm review-plan
• Review a plan in the optional TUI: uv run vlm review-plan --tui
• Apply edited review CSV decisions: uv run vlm apply-review
• Execute the plan (dry-run): uv run vlm execute
• Execute the plan (with confirmation): uv run vlm execute --confirm
• Rollback the last execution: uv run vlm rollback
• Generate reports: uv run vlm report [inventory|completeness|duplicates|summary]
• Manage quarantine: uv run vlm quarantine [list|add|restore]
• Manage file states: uv run vlm state [show|set|query|clear]

Running tests:

• Run all tests: uv run pytest

Development Conventions

• Code Style: Adheres to PEP 8, uses 4-space indentation, and includes type hints for public functions.
• Testing: Tests are located in the tests/ directory and written using pytest. The project also uses hypothesis for property-based testing. New features should be accompanied by tests.
• Commits: Commit messages should be clear and descriptive.
• Documentation: The README.md file is very comprehensive and should be kept up-to-date.
• Safety: A core principle is safety. Changes to the filesystem should be gated behind user confirmation (--confirm) and be reversible. The tool should never permanently delete files.