Initial deploy setup

2026-07-21 14:00:00 +02:00
commit b8091e59bd
285 changed files with 27854 additions and 0 deletions
@@ -0,0 +1,137 @@
+# 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;
+- 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:
+
+```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;
+- 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.