dl-organizer/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Core package lives in src/vlm/.
• CLI entrypoint is src/vlm/cli.py (vlm console script). Shared CLI helpers live in cli_helpers.py. Command logic is in commands/ (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd).
• Functional modules by concern: scanning (scanner.py), parsing (parser.py), enrichment (enrichment.py, cache.py, providers/), analysis/planning/execution (analysis.py, planner.py, executor.py), I/O helpers (io.py), utilities (utils.py), state/reporting/logging (state.py, reports.py, logging_config.py), config (config.py), models (models.py).
• Tests live in tests/ and mirror feature areas (e.g. tests/test_scanner.py, tests/test_cli_state.py, tests/test_enrichment.py).
• Project metadata and tool config are in pyproject.toml.

Build, Test, and Development Commands

• uv pip install -e . installs the package in editable mode.
• uv pip install -e ".[dev]" installs dev dependencies (pytest, hypothesis, pytest-cov, ruff).
• uv run pytest -q runs the full test suite.
• uv run pytest tests/test_logging.py runs a targeted test file during iteration.
• uv run ruff check src tests runs the linter (also in CI).
• vlm --help verifies CLI startup and available commands.

Coding Style & Naming Conventions

• Use Python 3.10+ idioms, 4-space indentation, and PEP 8 naming.
• Modules/functions/variables: snake_case; classes: PascalCase; constants: UPPER_SNAKE_CASE.
• Keep modules focused on a single responsibility; prefer small pure helpers in domain modules.
• Add type hints for public functions and non-trivial internal APIs.
• Use absolute imports in src/vlm/: from vlm.module import ... (avoid new relative imports).
• Ruff (E, F, I) is configured in pyproject.toml; CI runs ruff check src tests.

Testing Guidelines

• Framework: pytest; property-based tests use hypothesis.
• Naming (enforced in config): files test_*.py, functions test_*, classes Test*.
• Add/extend tests with each behavior change, including CLI error paths and edge cases.
• Prefer narrow unit tests for module logic plus targeted CLI integration tests via CliRunner.

Commit & Pull Request Guidelines

• Current history is minimal; use clear, imperative commit subjects (example: fix logging fallback for unwritable log dir).
• Keep commits focused; avoid mixing refactors and behavior changes unless tightly coupled.
• PRs should include: summary, rationale, test evidence (pytest output), and any CLI-visible output changes.
• Link related issues/tasks when applicable and call out config or migration impacts.

Security & Configuration Tips

• Do not commit local paths, personal media metadata, or generated state/log artifacts.
• Validate config changes against vlm --help and at least one end-to-end CLI flow before merging.

Documentation baseline

• Updated to reflect release 0.2.0 baseline as of 2026-06-01.
• Canonical release notes are tracked in CHANGELOG.md.
• Default workflow artifacts: artifacts/ (do not commit generated CSV/JSON).