# Matching- en scoringengine

## 1. Beslisvolgorde

```text
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:

```text
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.