FileScanner v2

Utilities for scanning course folders, collecting exam PDFs into organized result folders, refining the output for LLM analysis, exporting spreadsheet reports, and extracting screenshots for selected topics.

The project is built for local Windows use, especially when source material lives in synced folders or behind Windows shortcuts.

What It Does

• Scans configured root folders for exam-like PDF files.
• Creates Windows shortcuts in Scanner Results/all_found_tests/current/<year>/.
• Archives the previous all_found_tests run before starting a new scan.
• Moves detected duplicate shortcuts into Scanner Results/all_found_tests/current/dupes/<year>/ instead of deleting them.
• Can refine scanner output into a cleaner folder for LLM processing.
• Can send PDFs to Gemini for topic/question analysis.
• Can export JSON analysis into Excel.
• Can extract screenshots for a selected topic.

Setup

Create a virtual environment if you want one:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Install the Python packages used by the scripts:

pip install pymupdf colorama pywin32 openpyxl google-genai

Copy .env.example to .env and fill in your local values:

Copy-Item .env.example .env

.env is intentionally ignored by Git so API keys and local drive paths stay private.

Environment Variables

GEMINI_API_KEYS

One or more Gemini API keys separated by commas.

GEMINI_API_KEYS=key_1,key_2,key_3

SCANNER_ROOTS

One or more folders to scan, separated by semicolons.

SCANNER_ROOTS=C:\path\to\course-folder;D:\path\to\another-folder

SCANNER_IGNORED_SHORTCUT_ROOTS

Shortcut target roots that should not be followed.

SCANNER_IGNORED_SHORTCUT_ROOTS=G:\

Main Workflow

Run the scanner:

python scanner_v4.py

Useful scanner options:

python scanner_v4.py --no-dedupe
python scanner_v4.py --dedupe-only

Refine the scan output for LLM processing:

python refine_exams_for_llm.py

Analyze refined PDFs with Gemini:

python LLM_convert.py

Create the Excel report:

python excel_change.py

Extract screenshots for a topic:

python topic_screenshots.py

Scanner Behavior

Important scanner flags live near the top of scanner_v4.py:

REQUIRE_TEST_KEYWORD_PARENT = True
ARCHIVE_PREVIOUS_RUN = True
ENABLE_DUPLICATE_REMOVAL = True

REQUIRE_TEST_KEYWORD_PARENT limits accepted files to folders whose path matches test_keywords.

ARCHIVE_PREVIOUS_RUN moves the old Scanner Results/all_found_tests folder to a timestamped sibling before creating a fresh run:

Scanner Results/
  20260525_153012/
  all_found_tests/
    current/

ENABLE_DUPLICATE_REMOVAL compares candidate duplicates and moves extras into:

Scanner Results/all_found_tests/current/dupes/<year>/

Generated Files

Generated outputs are ignored by Git:

• Scanner Results/
• Excel Outputs/
• Question Screenshots/
• Topic Screenshots/
• exam_analysis*.json
• exam_analysis*.xlsx
• .env

Keep .env.example in Git as the public configuration template.

Notes

This project uses Windows shortcut APIs through pywin32, so the scanner is intended to run on Windows. Some scripts also assume local synced drives and Windows-style paths.