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

VLM Developer Guide

Project Structure

• src/vlm/cli.py: Entry point and command definitions.
• 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 using main.add_command().

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.
• MediaIdentity: Parsed and enriched information.
• PlanOperation: Definition of a file move/rename/quarantine.

Testing

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