GRITT combineert een gesprekservaring met een eigen kennisbank (RAG), een laag voor psychologische analyse (SLUIS) en een persona-laag (Mascheraro) voor consistente toon en gedrag. Doelen: (a) antwoorden die traceerbaar zijn naar ingestelde documenten, (b) ontwikkeling in gesprekken zichtbaar maken (vertrouwen, specificiteit, intimiteit), (c) personalisatie per gebruiker, en (d) beheer en diagnose eenvoudig houden voor admins.

Terminologie: “RAG” = Retrieval-Augmented Generation; “traits” = persoonskenmerken; “cites” = bronvermeldingen in antwoorden; “persona” = gedrags- en stijlprofiel van de assistent.

• Sessies (linkerkolom): maak/keer terug naar gesprekken; de actieve sessie bepaalt context & history.
• Bronvermeldingen (linkerkolom): verschijnt automatisch bij antwoorden die bronnen gebruiken.
• Composer (onder): tekst versturen, microfoon (inspreken), en voorlezen (laatste botbericht).
• Volume/mute: regelt uitsluitend TTS-uitvoer (stem: Maarten).
• Mijn documenten: linkt naar de User Catalog (privé-docs van de ingelogde gebruiker).

De Catalog toont de globale documenten (gedeelde kennisbank). Ingest kan via bestand (pdf/txt/json/docx) of platte tekst. Preview toont exact de chunk-tekst die RAG gebruikt.

Bij elke vraag embedden we de query en halen we top-K fragmenten op. De gebruikte fragmenten gaan als CONTEXT naar het model. Gebruikte documenten verschijnen als bronnen. Met User-aware RAG meng je globale context met privé-context.

Na elke beurt kan de server een compacte reflectie opslaan (samenvatting/focus). De monitor toont deze in een tabel en (compacte) grafiek. De monitor voedt MicroGalm/SLUIS waar relevant.

SLUIS maakt snapshots met top-eigenschappen (traits), kernsamenvatting (~100 woorden) en kernmetrics (vertrouwen, specificiteit, intimiteit, stabiliteit). Deze snapshots dienen als grondstof voor MicroGalm (individuele analyses) en Mascheraro (persona-afstemming).

De logspagina toont recente HTTP-verzoeken (status, duur, pad, user-agent) en helpt bij het opsporen van auth-fouten, timeouts en TTS/STT-problemen. Gebruik dit ook om RAG-hits en policywijzigingen te verifiëren.

• TTS: via de /audio/tts endpoint (unified). Standaard provider is Google (via TTS_PROVIDER=google), met o.a. stem nl-NL-Wavenet-B. Alternatief: Speechify (provider speechify).
• Diagnose: GET /audio/tts/google/voices toont de beschikbare (GCP) voices; GET /audio/tts/google/diag helpt bij credential-checks.
• STT: via POST /audio/stt (Whisper). De mic-knop in de UI neemt op en auto-verstuurt na ~3s stilte (zie stt.js).
• Mute/volume: beïnvloedt alleen de voorleesuitvoer in de client; het verandert niets aan de server-side transcriptie of het chat-antwoord.

Het admin-dashboard bundelt systeeminfo, sessiebeheer, ingest/RAG-debug en toegang tot MicroGalm, MacroGalm, SLUIS en de Microcatalogus (per gebruiker).

• Geen bronnen te zien? Controleer of de term in de Preview staat en of de score-drempel niet te hoog is.
• Catalog leeg? Doe een ingest opnieuw of backfill; daarna verschijnt het in de lijst.
• “Niet ingelogd” op admin-pagina’s: controleer token; herlaad met ?token=… of log opnieuw in.

Doel — per gebruiker structurele analyses en deelstudies opzetten (van 300–1500 woorden elk), gevoed door gesprekken, SLUIS-snapshots en (optioneel) privé-documenten. De resultaten kunnen gewogen meedoen in antwoorden en vormen de basis voor langere trajecten (coachingsplan, hypotheses, voortgang).

11.1 Invoer

• Gesprekslogs (samenvattingen per beurt of per n beurten)
• SLUIS-snapshots (traits, kern, metrics)
• Privé-documenten (user-catalogus; optioneel)
• Admin aantekeningen (observaties, hypotheses, labels)

11.2 Uitvoer

• Top-N thema’s/onderzoeksvragen voor deze gebruiker (met korte toelichting)
• Deelstudies per thema (300–1500 woorden)
• Kort eindbeeld per periode (bullet-samenvatting)

11.3 Workflow (UI)

1. Open Admin → MicroGalm.
2. Selecteer gebruiker en periode (of “alles”).
3. Klik Genereer/Herbereken om analyses bij te werken.
4. Markeer relevante deelstudies als actief zodat ze meetellen in de chat.

11.4 RAG-integratie

Actieve deelstudies worden in een eigen namespace opgeslagen (bijv. galm__user_{id}) en kunnen via User-aware RAG aan de context worden toegevoegd (conservatief budget, bijv. 20–30% van de user-context).

11.5 Richtlijnen

• Gebruik duidelijke, stabiele titels per deelstudie.
• Voeg bronnen toe waar mogelijk (citatie naar chatmoment of privédoc).
• Herbereken niet onnodig; kies vaste ankerpunten (bijv. wekelijks).

Doel — analyses en patronen op groepsniveau (cohort, project, experiment), zonder de privacy van individuele gebruikers te schenden.

12.1 Voorbeelden

• Top-thema’s per cohort (frequentie, gemiddelde confidence)
• Trendgrafieken van kernmetrics (specifiekheid, vertrouwen)
• Effect van interventies (A/B-prompts, persona-varianten)

12.2 Export

Exporteer geaggregeerde resultaten als CSV/JSON voor externe analyse. Individualiseer alleen met expliciete toestemming.

<!-- Header (standaard patroon) -->
<header class="header">
  <div class="wrap nav">
    <div class="links nav-left">
      <span id="brandBadge" class="nav-brand-text">GRITT</span>
      <nav class="nav-links-row">
        <a class="btn ghost" href="/index.html">Chat</a>
        <a class="btn ghost" href="/user-catalog.html">Documenten</a>
        <a class="btn ghost" href="/account.html">Account</a>

        <!-- admin-only (JS verbergt voor niet-admin) -->
        <a class="btn ghost nav-admin" href="/admin.html">Admin</a>
        <a class="btn ghost nav-admin" href="/admin-galm.html">MicroGalm</a>
        <a class="btn ghost nav-admin" href="/admin-sluis.html">Prota</a>
        <a class="btn ghost nav-admin" href="/admin-galm-cohorts.html">MacroGalm</a>
      </nav>
    </div>

    <div class="header-logo">
      <img src="/gritt-logo.png" class="nav-brand-logo" alt="GRITT logo">
    </div>

    <div class="links nav-right">
      <nav class="nav-links-row nav-links-row-right">
        <a class="btn ghost nav-admin" href="/admin-logs.html">Logs</a>
        <a class="btn ghost nav-admin" href="/admin-users.html">Users</a>
        <a class="btn ghost nav-admin" href="/admin-catalog.html">Catalog</a>
        <a class="btn ghost nav-admin" href="/admin-user-catalog.html">Privédocumentenmonitor</a>
      </nav>

      <span class="badge" id="who">…</span>
      <button class="btn ghost" id="logoutBtn">Uitloggen</button>
    </div>
  </div>
</header>

• Lege lijsten? Controleer permissies/token; herlaad met ?token=….
• Geen update? Kijk naar rate-limits en modelerrors in de logs; verlaag batchgrootte.
• Bronnen ontbreken? Check of deelstudies als actief gemarkeerd zijn en of user-RAG aan staat.

Doel — gebruikers kunnen eigen documenten uploaden die alleen voor henzelf en admins zichtbaar zijn. Deze privédocs kunnen (beleid-afhankelijk) meewegen in hun chat-context.

15.1 Locatie & navigatie

• Menu: Chat → Documenten (User Catalog).
• Upload (pdf/txt/docx/…), lijst met docs, titel wijzigen, preview en verwijderen.

15.2 Opslag & namespaces

• Global KB namespace: KB_NAMESPACE (default kb_v1).
• Privé-namespace per gebruiker: ${KB_NAMESPACE}__user_<userId> (dus bij default: kb_v1__user_123).
• Metadata van uploads staat in DB (tabel user_docs) met o.a. doc_id, title, mime, bytes, chunks, timestamps en external_ok.

15.3 Belangrijke knopjes

• Preview: toont chunk-tekst zoals die in RAG wordt gebruikt (debug van extractie/chunking).
• external_ok: markeert of een privédoc (delen) eventueel in gedeelde flows mag worden hergebruikt (alleen als je daar beleid voor hebt).

Doel — als admin een gebruiker kiezen, diens privédoc-lijst/preview bekijken, en per-user RAG-beleid instellen.

16.1 Wat je pagina doet

• Gebruiker kiezen: via GET /admin/users?limit=200 (lijst/zoek).
• Docs laden: GET /admin/userdocs?user_id=<id>.
• Preview: GET /admin/userdocs/preview?user_id=<id>&doc_id=<doc>.
• Digest/extrapolatie: preview via GET /admin/userdocs/digest en GET /admin/userdocs/extrapolation/preview; run via POST /admin/userdocs/extrapolation/run.

16.2 Per-user RAG policy

Deze policy wordt opgeslagen in user_settings en bepaalt of/hoe privédocs meewegen in chat:

• rag_user_enabled — privédocs meenemen (true/false).
• rag_user_topk — top-K voor de privé-namespace.
• rag_user_minscore — min-score drempel voor privéhits.
• rag_mix_user — bias voor zachte interleave-mix van privé vs global ranking.
• rag_user_ctx_share — welk deel van het contextbudget naar privéhits gaat.

Beheer via:

• GET /admin/userdocs/policy?user_id=<id>
• POST /admin/userdocs/policy

In de huidige codebase wordt “user-aware RAG” bereikt doordat userdocs-routes.js een contextbouwer exporteert naar app.locals.buildUserAwareContext. Die bouwer combineert (optioneel) de globale KB met de privé-namespace van de actieve gebruiker.

17.1 Hoe het werkt

1. Embed: vraag → query-vector (via embedFn(question)).
2. Retrieve global: retrieveFromNamespace(KB_NS, qv, topK, minScore).
3. Retrieve privé (alleen als rag_user_enabled): retrieveFromNamespace(KB_NS__user_<id>, qv, rag_user_topk, rag_user_minscore).
4. Wegingen:
   • Catalog-digests kunnen een boost krijgen via setting catalog_digest_weight.
   • Privé-hits kunnen per “kind” gewogen worden met w_user_primary en w_user_expo.
5. Mix + contextbudget: de uiteindelijke context wordt opgebouwd met een context cap (RAG_CONTEXT_CAP, default ~8000 chars) en een share naar privé (rag_user_ctx_share). Optioneel wordt de ranking “zacht” gemixt met rag_mix_user.

17.2 Troubleshooting

• Privédocs lijken genegeerd: check of userdocs-routes.js geladen wordt (anders gebruikt de server een fallback contextbouwer die alleen global doet).
• Te weinig/no hits: verlaag rag_user_minscore of verhoog rag_user_topk.
• Te veel privénuance: verlaag rag_user_ctx_share of rag_mix_user.

Mascheraro is de persona-laag van GRIT: het bepaalt stem, stijl, grenzen en rituelen van de assistent. Het is het “masker” waarachter de onderliggende modellen werken. Mascheraro laat je:

• Toon & taal vastzetten (vriendelijk, direct, wetenschappelijk, therapeutisch, etc.).
• Gedragsregels opnemen (eerst samenvatten, dan vervolgvraag; nooit pathologiseren; expliciet maken wanneer speculatief).
• Ritme bepalen (korte antwoorden, of juist reflecties aan het eind).
• Interactie met RAG sturen (altijd bronnen citeren, “zeg het als je het niet weet”, prioriteit voor user-context).

18.1 Waar wordt Mascheraro gebruikt?

• Chat: als deel van de system-prompt (voor alle antwoorden).
• MicroGalm: als schrijfstijl-kader voor deelstudies (consistentie).
• SLUIS: om toon/etikette te bewaken bij gevoelige thema’s.

18.2 Typische opbouw

Mascheraro v1
— Doel: empathisch, onderzoekend, nuchter.
— Taal: NL, helder, geen jargon tenzij nodig (dan uitleg).
— Gedrag:
  1) Begin kort met bevestiging/samenvatting (<2 zinnen).
  2) Beantwoord concreet; noem aannames.
  3) Sluit af met 1 vervolgvoorstel (optioneel).
— RAG:
  • Citeer gebruikte bronnen compact (titel, p., score≈).
  • Geen bron = expliciet maken (“dit is algemene kennis/inschatting”).

19.1 Instellingsniveaus

• Globaal (default persona voor iedereen).
• Per cohort (MacroGalm-pagina: experimenten, A/B-varianten).
• Per gebruiker (MicroGalm/SLUIS-profiel): kleine accentverschillen (uitlegtempo, emoji’s uit/aan).
• Per sessie (tijdelijk): bijvoorbeeld “korte zakelijke modus”.

19.2 Prompt-samenstelling (conceptueel)

system_prompt =
  [Mascheraro persona]
+ [veiligheid/guardrails]
+ [User-aware RAG context]
+ [sessie-specifieke instructies]

19.3 Voorbeeldsnippets

Mascheraro tone = "vriendelijk, precies, niet-belerend"
Mascheraro behavior:
- Vat eerst 1 zin samen.
- Meld aannames expliciet.
- Noem bronnen kort; geef geen lange quotes.
- Doe 1 concrete vervolgstap, tenzij user "geen tips".

19.4 Richtlijnen

• Laat persona niet de inhoud domineren: inhoud komt uit RAG/MicroGalm; persona kadert alleen toon/gedrag.
• Wees spaarzaam met format-regels; over-structuur kan antwoorden “houterig” maken.
• Versiebeheer: geef elke wijziging een versienummer (Mascheraro v2, v3…).