diff --git a/kern/growkit_poortwachter.py b/kern/growkit_poortwachter.py new file mode 100644 index 0000000..862addd --- /dev/null +++ b/kern/growkit_poortwachter.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +"""GrowKit Poortwachter — getypeerde beslisser vóór de LLM (1 okt 2026). + +Ontwerp: de review van Claude op Genius' voorstel (1 okt 2026). Twee trappen +werden drie: + +1. REGELS EERST — gratis en 100% voorspelbaar. Een @naam-mention hoort bij + die agent; een machine-alert van een eigen script draagt zijn ernst zelf. + Dit dekt naar verwachting het grootste deel van het interne verkeer. +2. CLASSIFIER — alleen voor vrije tekst van buiten (e-mail, leads, chat van + mensen). Een klein getypeerd model (bijv. Laya multilingual) levert een + klasse plus confidence. +3. LLM — bij twijfel. + +Harde regels (beleid, geen configuratie): + +- Machine-alerts en security-meldingen gaan NOOIT door een probabilistisch + filter. De handhaver is deze router zelf: bron=script slaat trap 2 over. +- Ruis wordt nooit weggegooid, alleen gedegradeerd en gelogd (append-only). + "Iets belangrijks als ruis" is de dure fout, niet "ruis als belangrijk". +- Drempel per klasse, niet één drempel: ruis vraagt meer zekerheid dan + urgent, want urgent-als-ruis is veel erger dan ruis-als-urgent. +- Een vast percentage van de zekere gevallen gaat alsnog naar de LLM + (audit). Anders ziet niemand de zelfverzekerde fouten van de filter. +- Zonder classifier: nooit stil gokken. Alles naar de LLM. + +Deze module beslist alleen WAAR iets heen gaat, nooit WAT er gebeurt. Hij +vervangt geen agent, geen review en geen poort: hij is een verkeersregelaar. +""" +import json +import re +from datetime import datetime, timezone + +# --- trappen --- +LAAG_REGEL = 1 +LAAG_CLASSIFIER = 2 +LAAG_LLM = 3 + +KLASSEN = ("urgent", "normaal", "ruis") + +# --- drempels: confidence die nodig is om een klasse te vertrouwen --- +# urgent laag (snel door), ruis hoog (nooit achteloos weggooien) +STANDAARD_DREMPELS = {"urgent": 0.60, "normaal": 0.75, "ruis": 0.90} + +# --- audit-steekproef --- +AUDIT_ELKE = 20 # 1 op 20 zekere gevallen (5%) alsnog naar de LLM + +# bekende familieleden — gelijk aan het familie-register +_AGENTEN = ("kairos", "riri", "vigil", "libra", "memoria", "codex", "genius") + +_MENTION = re.compile(r"@([a-z0-9_]+)", re.IGNORECASE) + + +def _nu() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def _besluit(laag: int, route: str, klasse: str, confidence, + reden: str, *, audit: bool = False, + gedegradeerd: bool = False) -> dict: + return { + "laag": laag, + "route": route, + "klasse": klasse, + "confidence": confidence, + "reden": reden, + "audit": audit, + "gedegradeerd": gedegradeerd, + "tijdstip": _nu(), + } + + +def _log_weg(logboek, besluit: dict, bericht: dict) -> None: + """Append-only spoor. Nooit overschrijven, nooit opruimen.""" + if logboek is None: + return + regel = dict(besluit) + regel["tekst"] = (bericht.get("tekst") or "")[:280] + regel["bron"] = bericht.get("bron", "") + with open(logboek, "a", encoding="utf-8") as fh: + fh.write(json.dumps(regel, ensure_ascii=False) + "\n") + + +def poort(bericht: dict, *, bron: str = "mens", classificeerder=None, + drempels: dict | None = None, audit_teller: int | None = None, + audit_elke: int = AUDIT_ELKE, logboek=None) -> dict: + """Bepaal de route van één bericht. Geeft altijd een besluit terug. + + bericht dict met minimaal "tekst"; mag "ernst" dragen (script-alerts) + bron "mens" (vrije tekst) of "script" (machine-alert, eigen bron) + classificeerder callable(tekst) -> (klasse, confidence). None = geen model. + audit_teller doorlopende teller; waarde deelbaar door audit_elke = audit + logboek pad naar een JSONL-bestand (append-only spoor) + """ + tekst = (bericht.get("tekst") or "").strip() + drempels = {**STANDAARD_DREMPELS, **(drempels or {})} + + # --- trap 1: regels --- + if bron == "script": + ernst = str(bericht.get("ernst", "urgent")).lower() + klasse = ernst if ernst in KLASSEN else "urgent" + b = _besluit(LAAG_REGEL, "direct", klasse, None, + "machine-alert: eigen bron zet de ernst zelf; nooit door " + "een probabilistisch filter", gedegradeerd=False) + _log_weg(logboek, b, bericht) + return b + + for naam in _MENTION.findall(tekst): + if naam.lower() in _AGENTEN: + b = _besluit(LAAG_REGEL, naam.lower(), "normaal", None, + f"@-mention van {naam.lower()}: regel, geen model") + _log_weg(logboek, b, bericht) + return b + + # --- trap 2: classifier --- + if classificeerder is None: + b = _besluit(LAAG_LLM, "llm", "onbekend", None, + "geen classifier beschikbaar — nooit stil gokken") + _log_weg(logboek, b, bericht) + return b + + klasse, confidence = classificeerder(tekst) + klasse = str(klasse).lower() + try: + confidence = float(confidence) + except (TypeError, ValueError): + confidence = 0.0 + + if klasse not in KLASSEN: + b = _besluit(LAAG_LLM, "llm", "onbekend", confidence, + f"classifier gaf onbekende klasse '{klasse}'") + _log_weg(logboek, b, bericht) + return b + + # twijfel of audit -> LLM + if confidence < drempels[klasse]: + b = _besluit(LAAG_LLM, "llm", klasse, confidence, + f"confidence {confidence:.2f} onder drempel " + f"{drempels[klasse]:.2f} voor '{klasse}'") + _log_weg(logboek, b, bericht) + return b + + if audit_teller is not None and audit_teller % audit_elke == 0: + b = _besluit(LAAG_LLM, "llm", klasse, confidence, + "audit-steekproef: vast aandeel zekere gevallen gaat " + "alsnog naar de LLM", audit=True) + _log_weg(logboek, b, bericht) + return b + + if klasse == "ruis": + b = _besluit(LAAG_CLASSIFIER, "gedegradeerd", klasse, confidence, + "ruis met voldoende zekerheid: gedegradeerd maar bewaard " + "(append-only), nooit weggegooid", gedegradeerd=True) + _log_weg(logboek, b, bericht) + return b + + b = _besluit(LAAG_CLASSIFIER, "afgehandeld", klasse, confidence, + f"klasse '{klasse}' met confidence {confidence:.2f}: " + f"geen LLM nodig, bespaart een call") + _log_weg(logboek, b, bericht) + return b diff --git a/tests/test_poortwachter.py b/tests/test_poortwachter.py new file mode 100644 index 0000000..0ecedbf --- /dev/null +++ b/tests/test_poortwachter.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 +"""Tests: de Poortwachter — getypeerde beslisser vóór de LLM (1 okt 2026). + +Ontwerp volgt de review van Claude (1 okt): drie trappen in plaats van twee. +1. Regels eerst — gratis en 100% voorspelbaar. @naam-mentions en + machine-alerts van eigen scripts hebben geen model nodig. +2. Classifier alleen voor vrije tekst van buiten. +3. LLM bij twijfel. + +Harde regels die deze tests vastleggen: +- Machine-alerts en security-meldingen gaan NOOIT door een probabilistisch + filter. De handhaver is de router zelf (bron=script slaat trap 2 over). +- Ruis wordt nooit weggegooid, alleen gedegradeerd en gelogd (append-only). +- Drempel per klasse, niet één drempel: "urgent als ruis" is veel erger dan + "ruis als urgent", dus ruis vraagt meer zekerheid dan urgent. +- Een vast percentage (5%) van de zekere gevallen gaat alsnog naar de LLM + (audit), anders ziet niemand de zelfverzekerde fouten. +- Zonder classifier: nooit stil gokken, altijd naar de LLM. +""" +import json +import sys +import tempfile +import unittest +from pathlib import Path + +REPO = Path(__file__).parent.parent +sys.path.insert(0, str(REPO)) + +from kern import growkit_poortwachter as pw + + +class TestTrap1Regels(unittest.TestCase): + """Trap 1: deterministische regels, geen model.""" + + def test_mention_routeert_naar_die_agent(self): + b = pw.poort({"tekst": "@vigil kun je de logs nalopen?"}, bron="mens") + self.assertEqual(b["laag"], pw.LAAG_REGEL) + self.assertEqual(b["route"], "vigil") + self.assertIsNone(b["confidence"]) + + def test_mention_roept_nooit_de_classifier_aan(self): + aangeroepen = [] + + def vals_aangeroepen(*_a, **_k): + aangeroepen.append(1) + return ("ruis", 0.99) + + b = pw.poort({"tekst": "@libra wat kost het vandaag?"}, bron="mens", + classificeerder=vals_aangeroepen) + self.assertEqual(aangeroepen, []) + self.assertEqual(b["laag"], pw.LAAG_REGEL) + + def test_mention_van_onbekende_naam_valt_terug_zonder_crash(self): + b = pw.poort({"tekst": "@onbekende_agent doe iets"}, bron="mens") + self.assertEqual(b["laag"], pw.LAAG_LLM) + self.assertEqual(b["route"], "llm") + + def test_script_alert_gaat_nooit_door_het_filter(self): + aangeroepen = [] + + def vals_aangeroepen(*_a, **_k): + aangeroepen.append(1) + return ("ruis", 0.99) + + b = pw.poort({"tekst": "POORT-WACHTER: nieuwe open poort 8080", + "ernst": "urgent"}, bron="script", + classificeerder=vals_aangeroepen) + self.assertEqual(b["laag"], pw.LAAG_REGEL) + self.assertEqual(b["route"], "direct") + self.assertEqual(b["klasse"], "urgent") + self.assertEqual(aangeroepen, [], "machine-alerts mogen nooit gefilterd worden") + + def test_script_alert_wordt_nooit_gedegradeerd_tot_ruis(self): + def alles_ruis(*_a, **_k): + return ("ruis", 0.99) + + b = pw.poort({"tekst": "STILLE WAKER: wachtrij 40 min stil", + "ernst": "urgent"}, bron="script", + classificeerder=alles_ruis) + self.assertTrue(b["gedegradeerd"] is False) + self.assertEqual(b["route"], "direct") + + +class TestTrap2Classifier(unittest.TestCase): + """Trap 2: classifier voor vrije tekst van buiten.""" + + def test_zekere_urgentie_wordt_afgehandeld_zonder_llm(self): + b = pw.poort({"tekst": "Mijn betaling is mislukt, dit moet nu"}, + bron="mens", classificeerder=lambda t: ("urgent", 0.95)) + self.assertEqual(b["laag"], pw.LAAG_CLASSIFIER) + self.assertEqual(b["klasse"], "urgent") + self.assertEqual(b["route"], "afgehandeld") + self.assertFalse(b["audit"]) + + def test_twijfel_gaat_naar_de_llm(self): + b = pw.poort({"tekst": "hmm vaag bericht"}, bron="mens", + classificeerder=lambda t: ("normaal", 0.40)) + self.assertEqual(b["laag"], pw.LAAG_LLM) + self.assertEqual(b["route"], "llm") + + def test_zonder_classifier_nooit_stil_gokken(self): + b = pw.poort({"tekst": "een gewoon bericht"}, bron="mens") + self.assertEqual(b["laag"], pw.LAAG_LLM) + self.assertEqual(b["route"], "llm") + self.assertIn("geen classifier", b["reden"]) + + +class TestDrempelPerKlasse(unittest.TestCase): + """Asymmetrische kosten: ruis vraagt meer zekerheid dan urgent.""" + + def test_ruis_drempel_is_strenger_dan_urgent_drempel(self): + d = pw.STANDAARD_DREMPELS + self.assertGreater(d["ruis"], d["urgent"]) + + def test_ruis_met_midconfidence_gaat_naar_de_llm_niet_de_prullenbak(self): + b = pw.poort({"tekst": "ok" * 50}, bron="mens", + classificeerder=lambda t: ("ruis", 0.80)) + self.assertEqual(b["laag"], pw.LAAG_LLM, "0.80 is te weinig zekerheid voor ruis") + + def test_ruis_met_hoge_zekerheid_wordt_gedegradeerd_maar_bewaard(self): + with tempfile.TemporaryDirectory() as tmp: + pad = Path(tmp) / "poortwachter.jsonl" + b = pw.poort({"tekst": "ok" * 50}, bron="mens", + classificeerder=lambda t: ("ruis", 0.97), + logboek=pad) + self.assertTrue(b["gedegradeerd"]) + self.assertEqual(b["route"], "gedegradeerd") + regels = [json.loads(l) for l in pad.read_text(encoding="utf-8").splitlines()] + self.assertEqual(len(regels), 1, "ruis moet bewaard blijven, niet weggegooid") + self.assertEqual(regels[0]["klasse"], "ruis") + + +class TestAuditSteekproef(unittest.TestCase): + """De filter kan zijn eigen zelfverzekerde fouten niet zien.""" + + def test_een_op_twintig_zekere_gevallen_gaat_alsnog_naar_de_llm(self): + b = pw.poort({"tekst": "gewone vraag"}, bron="mens", + classificeerder=lambda t: ("normaal", 0.99), + audit_teller=20) + self.assertEqual(b["laag"], pw.LAAG_LLM) + self.assertTrue(b["audit"]) + self.assertIn("audit", b["reden"]) + + def test_geen_audit_buiten_de_steekproef(self): + b = pw.poort({"tekst": "gewone vraag"}, bron="mens", + classificeerder=lambda t: ("normaal", 0.99), + audit_teller=21) + self.assertEqual(b["laag"], pw.LAAG_CLASSIFIER) + self.assertFalse(b["audit"]) + + +class TestSpoor(unittest.TestCase): + """Elk besluit laat een append-only spoor achter.""" + + def test_besluit_bevat_laag_route_en_reden(self): + b = pw.poort({"tekst": "@codex log dit"}, bron="mens") + for veld in ("laag", "route", "klasse", "confidence", "reden", + "audit", "gedegradeerd", "tijdstip"): + self.assertIn(veld, b) + + def test_logboek_is_append_only(self): + with tempfile.TemporaryDirectory() as tmp: + pad = Path(tmp) / "poortwachter.jsonl" + pw.poort({"tekst": "@vigil een"}, bron="mens", logboek=pad) + pw.poort({"tekst": "@libra twee"}, bron="mens", logboek=pad) + regels = pad.read_text(encoding="utf-8").splitlines() + self.assertEqual(len(regels), 2) + + +if __name__ == "__main__": + unittest.main()