dl-organizer/skills/vlm-library-workflow/references/dev-guide.md

Documentation Status

• Updated for the modular command architecture on 2026-02-16.

VLM Developer Guide

Project Structure

• src/vlm/cli.py: Entry point and thin command wrappers.
• src/vlm/parser.py: Regex-based filename parsing logic.
• src/vlm/enrichment.py: Pipeline for external metadata fetching.
• src/vlm/providers/: API implementations (e.g., TMDB).
• src/vlm/planner.py: Logic for mapping identities to filesystem operations.
• src/vlm/executor.py: Safe file manipulation and rollback logging.

Adding a New Command

1. Create a new module in src/vlm/commands/.
2. Define the command using @click.command().
3. Register it in src/vlm/cli.py with a Click-decorated function that delegates to the module implementation.

Modifying the Parser

• The parser uses a sequence of regex patterns in src/vlm/parser.py.
• Add new patterns to the PATTERNS list or improve existing ones.
• Always run pytest tests/test_parser.py after changes.

Data Models

See src/vlm/models.py for core data structures:

• VideoFile: Basic file metadata.
• MovieIdentity / SeriesIdentity: Parsed/enriched identity records.
• FileOperation: Definition of a move/rename/quarantine/no-op/preserve-directory operation.

Testing

• Unit Tests: pytest
• Property-based Tests: pytest tests/test_analysis_properties.py (uses Hypothesis).
• Integration Tests: pytest tests/test_reports_integration.py.