Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 161 additions & 0 deletions kern/growkit_poortwachter.py
Original file line number Diff line number Diff line change
@@ -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
171 changes: 171 additions & 0 deletions tests/test_poortwachter.py
Original file line number Diff line number Diff line change
@@ -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()
Loading