dl-organizer/GEMINI.md

GEMINI.md

Documentation Status

• Synced with repository refactor baseline on 2026-02-16 (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 (file info, video properties via ffprobe), and parses filenames to identify titles, years, seasons, and episodes.
• 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). The plan is executed only upon user confirmation.
• 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. Key modules include:

• cli.py: The main entry point for the CLI, using Click.
• commands/*.py: Implementation of the individual CLI commands (scan, parse, enrich, etc.).
• scanner.py, parser.py, enrichment.py, analysis.py, planner.py, executor.py: Core logic for the different stages of the workflow.
• 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.

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]"

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
• 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

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.