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`.