Supporting Reference 2: User Guide

This guide is for day-to-day operators. It covers how to run batches, review outputs, and publish safely. Use it after environment setup is complete.

R2.1 Before each run

1. Activate the correct Python environment (usually .venv313).
2. For EXE runs, set AMIR_PYTHON to the Python 3.13 interpreter before launch.
3. Confirm Ollama is reachable with ollama list.
4. Confirm input folders are available and writable paths are healthy (data/, logs/, data/ollama_tmp/).
5. If publishing is planned, verify FTP/MySQL credentials and endpoint availability.

Set-Location "\path\to\amir2000_image_automation"
.\.venv313\Scripts\Activate.ps1
ollama list
python .\main_set.py

R2.2 Start a batch

1. Open the Multi-Set UI from main_set.py.
2. Add one or more sets from local folders.
3. Review subject/location/folder mapping fields before starting. The Add set action is intentionally separated to reduce mis-clicks.
4. Subject input now auto-applies Title Case while typing (for example foggy bike path becomes Foggy Bike Path) and spellcheck runs with a safe debounce to avoid per-keystroke UI instability.
5. Use the resizable queue table to validate large runs. The table expands with the window and supports scrollbars for long set lists.
6. Start the batch and monitor stage progress + ETA in UI/console.

R2.2A Crash-safe continue flow

1. Reopen the Multi-Set app after an interruption or crash.
2. Click Recover crash session (next to Clear all).
3. Confirm the recovered set/pending counts shown in the dialog.
4. Continue normally with Start Batch.

Recovery source: data/multiset_session.json (or latest backup snapshot if present).

Add-set stability hardening: background AI subject generation now runs single-flight per selection (prevents overlapping workers while building many sets), and unexpected add-set callback failures are written to data/crash_runtime.log.

R2.3 What stages run automatically

The normal sequence is:

1. Validate sets
2. Prepare DB and copy to incoming
3. Extract EXIF and initial metadata
4. Insert or refresh review rows
5. AI quality scoring
6. Resize images for Ollama
7. Caption and keywords prefill
8. Open review editor

See Step 2: Workflow for full technical behavior.

R2.4 Review editor workflow

1. Use the Image n/x indicator to track position in long review queues.
2. In Multi-Set, confirm spellcheck health before batch build. Status now shows Spellcheck: ON/OFF next to the Add set controls.
3. Prioritize rows with weak quality or questionable caption/keywords.
4. Review and edit File_Name, Caption, alt_text, Keywords, Subject, and Location.
5. The review editor now uses larger multi-line fields for Caption, alt_text, and Keywords to fit full generated output without cramped edits.
6. Validate quality fields (QR, QC_Status) and adjust when needed.
7. Set each row decision explicitly: approved, pending, or rejected based on final quality.

R2.5 Decision rules for operators

• Approve when filename, metadata, and quality are publish-ready.
• Pending when additional review is needed and no publish should happen yet.
• Reject when output is unsuitable and should not proceed to publish.

Quality-first rule: speed should never override naming/metadata accuracy.

R2.6 Publish approved rows

1. Trigger publish from review editor after final row decisions are complete.
2. Uploader sends image + thumbnail assets to FTP target paths.
3. Metadata upsert is applied to MySQL by File_Name.
4. Local mirror DB is synchronized with canonical MySQL IDs.
5. On success, processed queue rows are cleared from review_queue.

R2.7 Post-run validation checklist

1. Check dist/logs/latest_run.log when running the EXE, or logs/latest_run.log when running Python directly.
2. Check logs/db_uploader.log for upload/upsert failures.
3. Spot-check published image and thumbnail URLs.
4. Verify expected records in MySQL photos_info_revamp.
5. Confirm queue statuses and mirror DB state are consistent.

R2.8 Fast recovery pointers

• If caption stage fails: validate Ollama model availability and retry.
• If publish fails: fix FTP/MySQL connectivity/credentials and re-run publish.
• If run crashes: inspect logs first, then follow rollback-safe recovery.

Detailed incident procedures are in Step 3: Runbook and Supporting Reference 3: Troubleshooting.

R2.9 Operator quality tips

• Use consistent naming language for similar subjects/locations across a batch.
• Avoid generic captions when subject-specific context is available.
• Keep geography keywords context-bound: if location is not USA, remove unrelated terms like usa or colorado.
• Use evidence-only keyword edits: do not keep mountain/lake/forest/river/valley/trail unless visibly supported or explicitly in context.
• Amsterdam-specific rule: prefer canal context; do not keep river/lake unless clearly evidenced.
• Filename time-of-day cues are authoritative: if filename includes sunrise, remove/replace conflicting sunset/dusk/evening terms; if filename includes sunset, remove/replace conflicting sunrise/dawn/morning terms.
• NL/polder context rule: remove mountain-specific drift terms (mountain, ridgeline, alpine, etc.) unless visually explicit in that set.
• Keep keyword sets relevant; remove noisy duplicates and weak generic terms.
• Reject weak outputs early rather than pushing low-quality metadata to publish.

R2.10 Continuation path

Continue to troubleshooting for issue patterns and targeted fixes.