75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# 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.
|