Run request analysis on demand on the VPS

docs/request-analysis-vps.md

@@ -0,0 +1,52 @@
+# Request Analysis On Debian 12 VPS
+
+This setup runs the request-analysis worker on the VPS only when needed.
+
+## How It Works
+
+- the API server accepts pending launcher requests
+- when a new pending request is created, the server schedules the worker
+- only one worker run is active at a time
+- if more pending requests remain after a run finishes, the server schedules another pass
+- you can also trigger a run manually through `POST /api/launcher-requests/process-pending`
+
+The worker itself still uses DeepSeek's hosted API, so the VPS is coordinating queue work instead of doing local inference.
+
+## Required Environment
+
+Recommended env file:
+
+`/srv/worldshaper/shared/worldshaper.env`
+
+Example:
+
+```bash
+DEEPSEEK_API_KEY=your-key-here
+REQUEST_ANALYZER_AUTORUN=1
+REQUEST_ANALYZER_PROVIDER=deepseek
+REQUEST_ANALYZER_MODEL=deepseek-v4-flash
+REQUEST_ANALYZER_PROMOTE_THRESHOLD=0.85
+REQUEST_ANALYZER_THINKING=disabled
+```
+
+## PM2 Deploy Hook
+
+The sample post-receive hook in [scripts/vps-post-receive.sample.sh](../scripts/vps-post-receive.sample.sh) now:
+
+- loads `/srv/worldshaper/shared/worldshaper.env` if present
+- restarts PM2 with `--update-env`
+- passes the request-analysis environment through on restart/start
+
+## Manual Trigger
+
+If you want to force a queue run:
+
+```bash
+curl -X POST http://127.0.0.1:5180/api/launcher-requests/process-pending
+```
+
+## Notes
+
+- autorun is opt-in through `REQUEST_ANALYZER_AUTORUN=1`
+- the worker only launches if pending requests exist
+- DeepSeek credentials stay on the VPS in the shared env file, not in the repo