Build an evidence-backed job-fit scoring API

1. Define the decision boundary

A fit score should help a candidate prioritize jobs, not make an employment decision. Record which constraints are hard gates, which are preferences, which facts are unknown, and who reviews the output. Do not infer experience, work authorization, language, location flexibility, or contract preference from silence.

The scorer emits a raw 0–100 fit score and a gate-adjusted 0–5 delivery score. Keep both: the first describes evidence alignment; the second reflects whether explicit hard requirements allow forwarding. Default shortlist mode filters on delivery score, not raw fit; use audit only when the caller needs every drop, hold, and failure.

2. Choose one candidate source

Send exactly one of candidateProfile, resume, or resumeText. A structured profile needs at least one actual role, target term, skill, or free-text fact. Add seniority, location, language, and work-arrangement constraints only when the candidate supplied them.

For production, obtain appropriate consent and minimize the payload. A fictional profile is safer for the first technical canary.

3. Choose one job source mode

• Search mode: select from ten supported developer-job sources, provide explicit keywords, and bound items per source, concurrency, and timeout.
• Supplied jobs: send complete nomad-agent-job-v1 objects with full description evidence.
• Dataset: provide an immutable dataset ID, not a mutable name or URL.
• Upstream run: provide one exact terminal successful run ID plus expectedSourceBuild to fail closed on drift.

Do not mix job sources in one score-jobs request.

4. Run a five-result canary

export APIFY_TOKEN="..."
export ACTOR_BUILD_NUMBER="latest"
node integrations/api/ai-job-fit-scorer-run-and-fetch.mjs

The maintained input searches three sources with a fictional profile, explicitly sets resultMode: "shortlist" and minDeliveryScore: 2, requests at most five evaluations, and sets a $0.10 maximum result charge. For a one-result smoke, reduce maxItems, maxAiItems, maxItemsPerSource, and aiConcurrency to one and set a $0.02 caller cap.

5. Verify before consuming

1. Poll only the returned run to terminal SUCCEEDED; require exit code 0 and a nonempty immutable build ID and number.
2. Read the same run’s RUN-SUMMARY and require nomad-ai-job-fit-run-summary-v4, algorithm name scoring-v3, expected guard values, valid result-policy count arithmetic, and actor/run/build fields matching that exact run receipt.
3. Fetch the exact default dataset and reconcile its count with counts.outputRows.
4. For shortlist, require every row to be scored at or above minDeliveryScore and chargedCount == outputRows. For audit, require resultFilteredOut == 0 and charge only non-failure rows.
5. Require closed nomad-ai-job-fit-v1 rows with nested canonical jobs and source provenance.
6. Boundedly re-read unsettled metadata from the same run; never switch to a latest-run lookup.

6. Store candidate-specific results safely

jobKey identifies the source posting. matchKey identifies the job/candidate/scoring-family relationship and is the table upsert key. evaluationKey is the more exact content-addressed receipt. Using jobKey alone can overwrite one candidate’s result with another’s.

Keep the full canonical evaluation for audit and derive nomad-ai-job-fit-destination-v1 only for a table. Protect candidate hashes, résumé-derived evidence, gap summaries, and source descriptions according to purpose and retention policy.

7. Interpret rather than worship the score

• Show the recommendation with supporting evidence and gaps, not just 82/100.
• Expose blocking gates and unknowns so a reviewer can correct candidate or job facts.
• Link back to the source posting and verify it before applying.
• Do not compare scores produced from different candidate snapshots, source builds, or algorithm versions as if everything else were equal.
• Keep a human responsible for application and hiring decisions.