VacatureRadar/docs/architecture/SCORING_ENGINE.md

Matching- en scoringengine

1. Beslisvolgorde

normalisatie
-> harde uitsluitingen
-> deterministische features
-> optionele AI-features (alleen aanvulling)
-> gewogen score
-> confidence
-> recommendation
-> append-only ScoreRun

Harde uitsluitingen hebben absolute voorrang. Een score van 99 kan een uitgesloten verplichte skill of regio niet overrulen.

2. Harde regels

Ondersteund of gepland:

• uitgesloten titelterm;
• uitgesloten/geen toegestane contractvorm;
• uitgesloten regio/gemeente;
• afstand boven maximum, behalve remote;
• uitgesloten verplichte skill;
• expliciete rijbewijs-/reis-/taalvereisten wanneer betrouwbaar geëxtraheerd;
• verlopen of niet-actieve vacature buiten de ranking.

Iedere uitsluiting bewaart een concrete reden. unknown_is_insufficient kan later per regel bepalen of ontbrekende data naar review gaat; veilige standaard is onbekend niet automatisch uitsluiten.

3. Componenten

Standaardgewichten, totaal 100:

Component	Gewicht	Kernsignalen
Content	25	titelovereenkomst, taken, weinig ongewenste support
Skills	20	gewenste skills in expliciete velden/tekst
Locatie	15	afstand, remote/hybrid, voorkeursregio
Voorwaarden	10	toegestane contract-/werkvorm
Werkgever	10	directe bron versus recruiter
Senioriteit	10	gevraagde ervaring versus profiel
Voorkeuren	10	publieke sector en andere soft signals

Bij aangepaste gewichten worden componentbijdragen genormaliseerd op de totale som.

• AI-boost is opt-in via profielinstelling en telt alleen mee als profielgewicht > 0.
• De AI-component is softwarematig begrensd (maximale bijdrage via ai-gewicht) om dominantie te vermijden.

4. Confidence

Confidence is niet hetzelfde als score. Een vacature kan inhoudelijk sterk lijken maar lage confidence hebben door ontbrekende werkgever, locatie of beschrijving.

Baselineformule in MVP:

confidence = 0.65 * extraction_confidence + 0.35 * field_completeness

Uitbreidingen mogen rekening houden met:

• provenancekwaliteit per veld;
• overeenstemming tussen aliassen;
• geocodingconfidence;
• parserspecifieke drift;
• AI-/deterministische featureconsistentie.

5. Recommendations

• strong — score ≥ topmatchthreshold en confidence ≥ 0,65;
• possible — score ≥ recommendationthreshold;
• weak — lager maar niet hard uitgesloten;
• hidden — minstens één harde uitsluiting.

Drempels zijn profielconfiguratie. De UI toont score en confidence apart.

6. Evidence en explainability

Een score bewaart:

• exacte componentbijdragen;
• positives;
• concerns;
• hard exclusions;
• afstand/evidence;
• profielversie;
• optionele model- en promptversie.
• AI-status (ok, disabled, timeout, invalid, error) en foutcategorie;
• gewichten (gevraagde vs. effectief toegepast, zodat cap zichtbaar is).

Copyregels:

• zeg "niet teruggevonden" in plaats van "ontbreekt" wanneer brondata onvolledig is;
• label inference als inference;
• toon maximaal enkele kernredenen bovenaan en volledige details uitklapbaar;
• geef geen kanspercentage op aanwerving zonder gevalideerd model.

7. Feedbackleren

Feedback kan alleen begrensde soft weights aanpassen. Learning staat standaard uit tot learning_enabled actief is.

Regels:

• learning kan uit;
• delta per feedbackactie klein en gelimiteerd;
• weight binnen 0..40;
• iedere wijziging maakt een profielrevisie;
• harde regels en bronpolicy worden nooit geleerd;
• een enkele actie leidt niet tot grote verschuiving (minimale sample-criteria per feature);
• gebruiker kan resetten en verschil bekijken.
• hidden feedback met reden en non-relevant categorieën wordt apart gelogd.

Feedbackregels worden als metadata op de feedback opgeslagen (feedback.metadata["learning"] met status, reden, feature, delta, sample count).

Offline evaluatie is beschikbaar via scripts/feedback_learning_report.py met feedbackcounts, churn en non-learning categorieën.

8. AI-rol

Toegestaan:

• support-/consultancy-/travelratio schatten;
• senioritylabel;
• korte Nederlandse samenvatting;
• evidencefragmenten selecteren;
• ambiguïteitswarnings.

Niet toegestaan:

• harde uitsluiting toevoegen zonder deterministisch verifieerbaar signaal;
• vacature verwijderen;
• URL bezoeken of tools aanroepen;
• source policy wijzigen;
• e-mail of sollicitatie verzenden;
• profiel zelfstandig herschrijven.

AI-input staat tussen duidelijke datamarkers, output volgt JSON-schema, temperatuur is 0 en alle waarden worden gevalideerd/geclamped. Uitval is een normale fallback, geen pipelinefout.

• AI-status en evidence worden altijd opgeslagen in ScoreRun.evidence en vallen nooit terug op hard-exclusions of sourcepolicywijzigingen.