Env-tunable per-run caps (MAX_FILES_PER_RUN, MAX_RUN_DURATION_SECS)

The two per-run limiters in main.py now read from the environment with
their current hardcoded values as defaults. Lets us tune cadence (e.g.
200 → 500 newly-tagged files per click) without rebuilding the image —
edit .env and `docker compose up -d --force-recreate api`.

docker-compose.yml threads both vars into the api container.
.env.example documents them with empty defaults.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -11,6 +11,11 @@ GEMINI_API_KEY=your_gemini_api_key_here
 # Example: BOX_FOLDER_IDS=380274488839,123456789012
 BOX_FOLDER_IDS=
 
+# Per-run caps. Empty → defaults in main.py (200 newly-tagged files, 14400 s = 4h).
+# Bump these when you're confident in Gemini quota / Box throughput headroom.
+MAX_FILES_PER_RUN=
+MAX_RUN_DURATION_SECS=
+
 # ── Postgres ───────────────────────────────────────────────────────────────────
 POSTGRES_USER=marriott
 POSTGRES_PASSWORD=change_me

docker-compose.yml

@@ -45,6 +45,10 @@ services:
       # One or more Box folder IDs to walk recursively (comma-separated).
       # Empty → falls back to the hardcoded default in main.py.
       BOX_FOLDER_IDS: ${BOX_FOLDER_IDS:-}
+      # Per-run caps (newly-tagged file count and wall-clock seconds). Defaults
+      # in main.py are 200 and 14400 (4h); override here to tune without a rebuild.
+      MAX_FILES_PER_RUN: ${MAX_FILES_PER_RUN:-}
+      MAX_RUN_DURATION_SECS: ${MAX_RUN_DURATION_SECS:-}
       TZ: ${TZ:-UTC}
       # Auth — set DEV_AUTH_BYPASS=true to skip MSAL while you wire it up.
       DEV_AUTH_BYPASS: ${DEV_AUTH_BYPASS:-true}

main.py

@@ -62,8 +62,10 @@ DESCRIPTION_MAX_LENGTH = 255
 # Counts only NEWLY-tagged files (skipped-as-already-tagged is free and doesn't count).
 # Shared across images and videos. When either cap is hit, the run exits cleanly
 # with a summary; the next scheduled run picks up the remaining untagged files.
-MAX_FILES_PER_RUN = 200       # hard cap on newly-tagged files per run
-MAX_RUN_DURATION = 4 * 3600   # hard cap in seconds (4 hours; stays well under the 6h systemd timeout)
+# Overridable via env so they can be tuned without a code rebuild — edit .env
+# then `docker compose up -d --force-recreate api`.
+MAX_FILES_PER_RUN = int(os.environ.get("MAX_FILES_PER_RUN", "200"))   # newly-tagged files
+MAX_RUN_DURATION = int(os.environ.get("MAX_RUN_DURATION_SECS", str(4 * 3600)))  # wall-clock seconds
 
 # ── 1. Box Client ────────────────────────────────────────────────────────────