docs/BATCH_JOBS.md

Background batch jobs (launcher)

Large launcher queues can be processed server-side in chunks: SerpAPI for Google results, then fetch + score (OpenRouter AI or heuristic). State lives in Upstash Redis; Upstash QStash wakes your deployment (e.g. Hugging Face Space) with HTTPS callbacks so work continues after you close the tab.

Troubleshooting: “Job not found” right after starting a batch

The Upstash Redis client parses JSON on GET by default. This app stores each job as a JSON string with SET and expects a string back on GET. If deserialization is left on, GET returns an object, the loader treats the job as missing, and the status page shows Job not found even though Redis has the key. The code sets automaticDeserialization: false on the Redis client (lib/batch-jobs/redis.ts). After upgrading, restart the deployment so a new process picks up the client config.

Required services

1. SerpAPI — SERPAPI_API_KEY.
2. Upstash Redis — REST URL and token:
   • UPSTASH_REDIS_REST_URL
   • UPSTASH_REDIS_REST_TOKEN
3. Upstash QStash — publish token and signing keys (for verifying callbacks):
   • QSTASH_TOKEN — used to enqueue the next chunk after each run.
   • QSTASH_CURRENT_SIGNING_KEY — used to verify incoming requests to the chunk endpoint.
   • QSTASH_NEXT_SIGNING_KEY — optional; use during key rotation.

Public URL (critical for QStash)

QStash must call a stable HTTPS URL that reaches your app. Set:

• BATCH_PUBLIC_APP_URL — origin only, no trailing slash, e.g. https://your-space.hf.space or your Vercel URL.

Hugging Face Spaces (important)

Do not use the gallery link as the public URL:

• Wrong: https://huggingface.co/spaces/zimejin/Job-Scorer (Space page on hf.co — this is not your container’s API host).
• Right: https://<subdomain>.hf.space — the direct app URL shown when you open the Space (App tab / embedded app). It usually looks like https://zimejin-job-scorer.hf.space (check your Space’s Settings → Details for the exact *.hf.space value).

Use that https://....hf.space value (no path) for BATCH_PUBLIC_APP_URL, and use the same URL in the browser when you run batch jobs so /api/... calls hit your app.

The app publishes chunk work to:

{BATCH_PUBLIC_APP_URL}/api/internal/batch-jobs/chunk

Signing verification uses this same base URL. If verification fails, confirm the URL matches exactly what QStash calls (scheme, host, path).

Optional: OpenRouter (AI scoring)

• OPENROUTER_API_KEY

If unset, scoring falls back to heuristics.

Optional tuning (environment)

Variable	Purpose
BATCH_SERP_DELAY_MS	Delay between SerpAPI calls within a chunk (default 1200).
BATCH_SCORE_DELAY_MS	Delay between listing fetch/score steps (default 1500).
BATCH_QUERIES_PER_CHUNK	Max Serp queries processed per QStash delivery (default 5).
BATCH_SCORES_PER_CHUNK	Max listings scored per delivery (default 3).
BATCH_MAX_STORED_HITS	Cap on stored passing hits in Redis (default 500).
BATCH_MIN_ROLE_FIT	Default min role score (overridable in API body).
BATCH_MIN_GLOBAL_REMOTE	Default min remote score.
BATCH_ALLOWED_VERDICTS	Comma list: Strong Match, Possible, Skip.

Manual resume (debug / recovery)

If QStash delivery fails, you can advance the job one chunk with:

POST /api/launcher/batch-jobs/{id}/resume

Header:

Authorization: Bearer {BATCH_RESUME_SECRET}

Set BATCH_RESUME_SECRET in the deployment environment. This runs the same logic as the QStash callback without signature verification.

API

• POST /api/launcher/batch-jobs — body: { queries: [{ q, tbs? }], options }. Returns { id, status } and enqueues the first chunk.
• GET /api/launcher/batch-jobs/{id} — progress + top hits (sorted, capped by topK).
• POST /api/internal/batch-jobs/chunk — QStash-only (or manual resume via the resume route above); body { jobId }.

UI

Job search launcher → Background batch job: precision checkbox, caps, and Start background batch opens /job-launcher/batch/{id} for polling.

Recent jobs and JSON export (browser)

• Recent batch jobs on the launcher is stored in localStorage only (this browser / profile). Clearing site data removes the list; it is not synced to a server.
• On the batch status page, Download JSON saves an archival snapshot of the current job payload (plus exportedAt metadata). Server-side jobs still expire from Redis after about 7 days as before—export if you need a long-term copy.