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;
• een titelgestuurde IT-grens; ambigue field-/implementatietitels vereisen daarnaast een sterk IT-contextsignaal in de vacaturetekst;
• 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	30	titelovereenkomst, taken, weinig ongewenste support
Skills	25	gewenste skills in expliciete velden/tekst
Locatie	20	afstand, remote/hybrid, voorkeursregio
Voorwaarden	10	toegestane contract-/werkvorm
Werkgever	10	directe bron versus recruiter
Voorkeuren	5	publieke sector en andere soft signals

Bij aangepaste gewichten worden componentbijdragen genormaliseerd op de totale som.

• De profielervaring is uitsluitend informatieve context. Gevraagde ervaringsjaren en senioriteitslabels veranderen de score, aanbeveling en uitsluitingen nooit.
• Een breed cv-profiel wordt niet bestraft omdat veel relevante skills zijn geselecteerd: maximaal vier aangetroffen profielskills volstaan voor de volledige skillcomponent. Niet-aangetroffen voorkeurskills blijven evidence, maar worden niet als bewezen tekort of concern gepresenteerd.
• 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;
• presenteer niet-vermelde cv-skills niet als tekort; alleen expliciet aangetroffen skills zijn positieve evidence;
• 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 als informatieve extractie, zonder score-invloed;
• 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.