rename: auto-name your files using gemini

what it does

• walks a folder, finds files by extension (e.g., jpg,png,pdf)
• asks a model to suggest a better base name for each file
• renames the file to "-flash" (you should change the -flash to something else)
• logs everything to the console and to script/rename.log
• writes a simple report mapping old paths to new names (optional json)

quick setup

1. make sure you have python 3.10+ installed
2. create a virtualenv (optional but recommended)
   • uv venv
3. install deps
   • uv add google-genai python-dotenv
4. set your api key
   • put AI_API_KEY=your_key_here in a .env file at the repo root, or export it in your shell

how to run

• uv run main.py <src_dir> <exts>
  • example: uv run main.py /path/to/folder jpg,png,pdf,jpeg

options (env vars)

• RENAME_ALLOW_OVERWRITE=1 allow renaming onto an existing file (default: blocked)
• RENAME_REPORT_JSON=/path/to/report.json write a json report of all outcomes

what to expect

• the tool processes files concurrently and prints progress like Completed N/M
• large files can take longer; the run finishes once every file is done (for pdfs, it is probably better to use a pdf reader first to extract the text)
• nothing is deleted; files are only renamed in place
• if the model fails for a file, it is skipped and noted in the report

example

• RENAME_REPORT_JSON=report.json uv run main.py ./samples jpg,png,pdf
  • produces script/rename.log and report.json with a per-file status

troubleshooting

• if you see retries or delays, the model may be busy or the file is large
• ensure AI_API_KEY is set and valid
• to avoid overwriting files with the same final name, keep RENAME_ALLOW_OVERWRITE unset

plan

• i dont like how long larger files take, there is probabaly some way i can optimize this. compress images, extract text from pdfs, etc.