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