AI Image Renamer

Rename image files using a vision model: it looks at each image, gets a short description, turns that into a safe filename, and renames files without overwriting (suffixes like _2, _3 when needed). Every run can write a JSONL log so you can undo later.

---

Web app

The browser UI (Gradio) supports Gemini (cloud) and LM Studio (local). Use Preview (Dry Run) first, then Apply Rename when you are happy. There is a Test Connection button and an Undo tab that works from a log path.

---

Start the app (quick steps you can bookmark)

Do this from the project folder (where app.py lives), e.g. D:\AI_software\Github_repos\ai-image-renamer.

Step	What to do
1	Open a terminal in that folder (Explorer: address bar → type cmd or use PowerShell and cd there).
2	First time only: install dependencies: python -m pip install -r requirements.txt
3	Start the UI: python app.py
4	Open your browser to http://127.0.0.1:7861 (this repo pins host/port there).
5	When finished, go back to the terminal and press Ctrl+C to stop the server.

If the page does not load, confirm the terminal still shows the app running and that nothing else is blocking 127.0.0.1:7861.

---

Folder path in the web app

• Full path (recommended): e.g. D:\Photos\batch1 — always unambiguous.
• Relative path: resolved from the project folder (next to app.py), not from “wherever the terminal was.” Example: test_images → …\ai-image-renamer\test_images.

After a run, Run status includes a Folder: … line showing the path that was used.

---

API keys and providers

• Gemini: put GEMINI_API_KEY in .env, or paste a key in the UI for that session only (not written to logs).
• LM Studio: run LM Studio, load a vision model, start the local server. Defaults in the UI match http://127.0.0.1:1234/v1.

The command-line tool can also use OpenAI if configured; the web UI is limited to Gemini + LM Studio.

---

First-time setup

1) Install Python packages

python -m pip install -r requirements.txt

2) Create .env (optional if you paste keys in the UI)

Copy setup_env_example.txt to .env and fill in what you use.

Gemini example:

GEMINI_API_KEY=your_key_here
GEMINI_VISION_MODEL=gemini-2.5-flash

LM Studio example:

LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
LMSTUDIO_API_KEY=lm-studio
LMSTUDIO_MODEL=your_loaded_vision_model_id

---

Command line (auto_renamer.py)

Same engine as the web app: preview by default, --apply to rename, undo with a log file.

Preview (no renames):

python auto_renamer.py test_images --provider gemini

Apply:

python auto_renamer.py test_images --provider gemini --apply

LM Studio:

python auto_renamer.py test_images --provider lmstudio --model your-vision-model-id

List Gemini models for your key:

python auto_renamer.py list-models --provider gemini

Undo (use the log path your run printed):

python auto_renamer.py undo "rename_logs\your_log.jsonl" --apply

Omit --apply on undo for a dry preview. Full help:

python auto_renamer.py --help

---

Safety defaults

• CLI runs in dry-run until you pass --apply.
• Collision-safe unique names.
• JSONL logs under rename_logs/ for audit and undo.