Automated PDF Invoice Sorter – Dest Python

Task: Create a production‑ready Python automation script named invoice_sorter.py that scans a directory of PDF invoice files, extracts key metadata (vendor name, invoice date, and invoice number), and moves each PDF into a structured folder hierarchy based on that metadata. The solution must be fully functional, well‑documented, and include supporting files (requirements, README, unit tests).

Requirements:

1. Environment & Dependencies

   • Use Python 3.10+ and a virtual environment.
   • Required packages: pdfplumber, pytesseract, Pillow, PyPDF2, python-dotenv, loguru.
   • Provide a requirements.txt file listing exact versions.

2. Configuration

   • Accept configuration via a .env file (e.g., SOURCE_DIR, DEST_ROOT, TESSERACT_CMD, LOG_LEVEL).
   • Include a sample .env.example with comments explaining each variable.

3. CLI Interface

   • Use argparse to support:
     • --source (override SOURCE_DIR)
     • --dest (override DEST_ROOT)
     • --dry-run (show actions without moving files)
     • --log-level (override LOG_LEVEL)

4. Metadata Extraction

   • First attempt to extract text with pdfplumber.
   • If the PDF is image‑based or text extraction fails, fall back to OCR using pytesseract.
   • Identify the following fields using robust regex patterns (handle common variations):
     • Vendor Name – e.g., “Acme Corp”, “XYZ Ltd.”
     • Invoice Date – accept formats MM/DD/YYYY, DD-MM-YYYY, YYYY.MM.DD; output ISO YYYY-MM-DD.
     • Invoice Number – alphanumeric patterns like INV-12345 or 2023/001.

5. Folder Structure

   • Destination path: ////
   • Rename the file to Invoice__.pdf (e.g., Invoice_INV-12345_2023-07-15.pdf).

6. Logging & Error Handling

   • Use loguru for structured logs (to console and invoice_sorter.log).
   • Log each processed file, extracted metadata, and any errors (e.g., missing fields, unreadable PDF).
   • If required metadata cannot be extracted, move the file to /Unsorted/ and log the reason.

7. Idempotency & Safety

   • Ensure the script can be re‑run without duplicating or overwriting files.
   • If a target filename already exists, append a numeric suffix (_1, _2, …).

8. Testing

   • Provide a tests/ directory with at least three pytest cases:
     1. Successful extraction from a text‑based PDF.
     2. OCR fallback for an image‑only PDF.
     3. Handling of a PDF missing one of the required fields (should go to Unsorted).

9. Documentation

   • Include a comprehensive README.md covering:
     • Project overview.
     • Setup instructions (virtualenv, installing Tesseract OCR, pip install -r requirements.txt).
     • Configuration guide.
     • Usage examples (with CLI flags).
     • Testing instructions.

10. Code Quality

    • Use type hints throughout.
    • Follow PEP 8 style.
    • Include docstrings for all functions/classes.
    • Provide a main() entry point guarded by if __name__ == "__main__":.

Expected Output Format:

• invoice_sorter.py – full script with shebang, imports, functions, CLI, and entry point.
• .env.example – sample environment file with comments.
• requirements.txt – pinned package versions.
• README.md – markdown documentation as described.
• tests/test_invoice_sorter.py – pytest file with the three required test cases.
• Any additional helper modules (if you choose to split logic) should be included and referenced in the README.

Please deliver all files in a single Markdown code block per file, clearly labeled with the filename (e.g., python\n# invoice_sorter.py\n...), so the buyer can copy each file directly. Ensure the solution is ready to run after following the README setup steps.