FUGA – Admin guide

Deze handleiding is bedoeld voor twee doelgroepen. Daarom zijn technische stukken herkenbaar als TECH en staan ze verder naar beneden. Niet‑technische lezers kunnen die blokken gerust overslaan.

Terminologie: in sommige interne stukken wordt “VUGA” gebruikt; in de UI en routes heet het systeem FUGA. Het gaat om dezelfde module.

1. Wat is FUGA?

FUGA is een curriculum‑tutor module binnen GRITT. Je laadt curriculum‑materiaal in (vaak PDF), FUGA splitst het in kleine elementen en relaties, en vervolgens kan het systeem per cliënt het begrip volgen.

1.1 Doel in één zin

FUGA helpt leren door het curriculum op te breken in “wat moet je snappen”, en daar evidence uit gesprekken aan te koppelen.

1.2 Voorbeeld (intuïtief)

Stel je uploadt een PDF “Politieke filosofie 1950‑heden”. Ingest maakt bijvoorbeeld: units per week, daarbinnen definities (wat betekent begrip X), proposities (stelling Y), en logische punten (relaties/argumentstructuur). Een cliënt die later “Cohen bekritiseert gelijkheid…” uitlegt, levert evidence voor relevante elements.

Wat-is-wat: de FUGA admin-pagina

Hieronder staat een korte rondleiding door de pagina admin-fuga.html (wat je waar vindt, en waarvoor het bedoeld is). De screenshots zijn een statische weergave van de layout; in de echte omgeving vullen lijsten en grafiek zich pas na het selecteren van een project en een cliënt.

Topbarnavigatie

Links zie je de module-identiteit. Rechts: Handleiding (opent deze guide) en Logout.

1) Cliëntselector + dossiercliënt-instellingen

• Zoek cliënt… + dropdown: kies een cliënt, of filter op naam.
• Refresh: herlaadt de cliëntenlijst (handig na nieuw account).
• FUGA aan: togglet of deze cliënt überhaupt door FUGA wordt gevolgd.
• Actief project: welk curriculum-project voor deze cliënt “dominant” is bij context/matching.
• Projecten van deze cliënt: laat zien welke projecten al aan deze cliënt hangen (meestal 1 actief).
• Opslaan: schrijft instellingen weg; Dossier: laadt mastery + recente evidence.
• Rechts: Dossier-paneel + optionele Debug (raw JSON) (voor diagnose).

2) Activiteit & clusterkaartgrafiek + overlay

• 2D/3D: wissel rendering-mode (3D is default).
• Toon cliënt activiteit: zet de overlay (mastery/activity) aan/uit.
• Labels: toont/verbergt labels in de kaart (handig bij “zoomed-out” clusters).
• Centreer: reset camera/positie; Refresh: laadt grafiek opnieuw.
• Scope: curriculum / macro / course / unit; bij macro/course/unit kies je rechts het onderwerp.
• Layout: Thema/cluster (relaties) versus Links→rechts (curriculumvolgorde).
• Zwakke chronologie: laat sequence-links licht meewegen (alleen als je dat expliciet wil).
• Gloed: laatste activiteit: highlight waar de laatste cliënt-evidence zit.
• Tijd-slider: filtert overlay op recency (links=oud, rechts=nu).
• Experimenteerpaneel: preset + sliders voor backend-SIM en frontend-layout; Pas toe herlaadt de grafiek met nieuwe parameters.
• Onderin: SIM strength verdeling (histogram), Legenda, en Details (klik node/link).

Let op: als er geen cliënt geselecteerd is, kan de kaart geblokkeerd worden (“Selecteer eerst een cliënt”). Dat is expres: overlay en time-filter zijn cliënt-specifiek.

3) Project selectie + documenten + structuurbeheer

• Project selectie: kies een project, refresh, of Verwijder (met wachtwoord).
• Download backup: exporteer project of alle projecten (metadata) als JSON.
• Projectdocumenten: inventaris van uploads in dit project (met acties per file).
• Structuurbeeld: taxonomische boom (macro→course→unit) + mapping van bestanden; Ververs laadt opnieuw.
• Structuur-chat: conversatie met de organiser-assistent; daaruit rolt een Voorgesteld commando dat je kunt testen (dry-run) en daarna toepassen.

4) Upload & analyseinvoer + ingest

• Kies bestand → Upload PDF: zet een PDF in het geselecteerde project.
• Analyseer / ingest: start ingest (extract → units/elements + embeddings).
• Admin (curriculum) vs Cliënt (evidence): bepaalt of de upload curriculum is, of een cliënt-dossierstuk (bewijs/essay).
• Voortgangsbalk + status-chips: snelle feedback over ingest-status en aantallen.
• Hulp nodig-box: verschijnt als FUGA niet zeker weet waar een document thuishoort; je kunt een voorstel toepassen of negeren.

5) Curriculum explorerinhoud inspecteren

Met de explorer kun je handmatig door macro/courses/units klikken en elementen laden. Dit is handig om snel te toetsen of de ingest inhoudelijk klopt (zonder grafiek).

6) Testsdiagnose

• Test context: korte end-to-end check of tutor-context en project-koppeling werken.
• Test vector: check of retrieval hits teruggeeft voor een query.
• De output verschijnt in de twee monospace boxen onderaan.

Pop-ups (modals)

Sommige acties vragen bevestiging of openen een viewer. Dit voorkomt per ongeluk destructieve acties.

Project verwijderenwachtwoordconfirmatie

Bestand verwijderenwachtwoordconfirmatie

Tekst viewerextracted text

Deze viewer gebruik je om snel te verifiëren of PDF-extractie correct was (zonder het originele PDF-layout-gedoe).

2. Begrippen (met schema)

FUGA modelleert curriculum in lagen. In jouw huidige implementatie is de top meestal een project. Daaronder zit optioneel een macro-sectie (bijv. “Jaar 1”), daaronder courses, dan units (bijvoorbeeld weken), en dan elements (kleine kennisstukjes zoals definities, proposities en conclusies).

2.1 Mastery en evidence (voorbeeld)

Evidence is een concreet bewijsstuk (meestal een citaat/snipper) uit een chat of ingeleverd document van de cliënt, dat door FUGA aan één of meer elements wordt gekoppeld. Mastery is de (voorlopige) beheersing van een element op basis van die evidence.

• Bronnen: chat (cliënt), chat (assistant), en later ook “essays/werkstukken” (via upload).
• Wat wordt opgeslagen: snippet (letterlijk), paraphrase (samenvatting), scores voor literal en higher‑order, privacy-score (0–10), en optioneel “contradiction”.
• Schaal: mastery wordt intern als 0–10 bijgehouden (dus 0–100%); de grafiek normaliseert dit naar een kleur‑overlay.
• Belangrijk: niet elk bericht wordt met alle elements vergeleken. FUGA doet retrieval → shortlist → LLM‑judge en slaat alleen relevante evidence op.

2.2 Admin overrides (wanneer wel/niet)

Overrides gebruik je als ingest tekst onduidelijk is, of als importance verkeerd is. Overschrijven hoort traceerbaar te zijn en mag ingest niet “vervuilen”.

3. Workflow voor admins (zonder code)

Dit is de kern voor niet‑technische admins: maak project, upload PDF, start ingest, check aantallen, configureer cliënt.

3.1 Wat moet je na ingest controleren?

• Counts: hoeveel macro-secties/courses/units/elements zijn aangemaakt?
• Verdeling: zien weeks/units er logisch uit (niet alles in één unit)?
• Bestanden: klopt de extracted text als je een bestand opent?
• Analyse-document: open “Analyse” op een bestand en check of de elements inhoudelijk bruikbaar zijn.
• Incidents/structuur-hulp: zijn er “hulp nodig” meldingen of open incidenten?

3.2 Client instellen

Selecteer een cliënt, zet FUGA aan (enabled), en koppel een actief project. Vanaf dat moment worden chatberichten (op de achtergrond) geobserveerd en kan het dossier mastery + evidence gaan vullen.

3.3 Documentenlijst, scope en analyse per bestand

Onder “Projectdocumenten” zie je per upload een rij met knoppen. Dit is je controlepunt: het is de brug tussen bronmateriaal en curriculum‑elements.

• Origineel: opent de originele PDF.
• Tekst: toont de geëxtraheerde tekst (hier zie je snel extractieproblemen).
• Analyse: opent een analyse-document met units + elements. Als je ook een cliënt selecteert, zie je daar bovendien zijn/haar evidence (bewijsstukken) die aan elements zijn gekoppeld.
• Scope: een document kan op curriculum-, macro-, course- of unit-niveau “horen”. Je kunt scope later aanpassen (admin-knop).
• Verwijder: admins kunnen een document verwijderen (met wachtwoordconfirmatie). Client‑uploads kunnen “locked” zijn, zodat ze niet per ongeluk verdwijnen.
• PDF (analyse): in het analyse‑document kun je via print/PDF een snapshot downloaden (handig voor delen of archiveren).

3.4 Structuur & document-mapping (boomweergave)

Het “Structuur & document-mapping” paneel laat de taxonomische boom zien (macro → course → unit) en welke bestanden waar landen. Als FUGA na upload/ingest niet zeker weet waar iets thuishoort, verschijnt er een hulp nodig-melding (incident). Je kunt dan:

• handmatig commando’s uitvoeren (deterministisch), of
• een AI-commando laten voorstellen (LLM), waarna jij beslist.

Opzet: FUGA mag onzeker zijn, maar moet dat expliciet maken en een corrigeerbaar voorstel doen (zoals je eerder specificeerde).

3.5 Clusterkaart: links-modus, layout en experimenteerpaneel

De clusterkaart is bedoeld om thematische eilanden zichtbaar te maken (op basis van relaties) en om daaroverheen cliënt‑activiteit te leggen. In de huidige build heb je drie belangrijke knoppen/keuzes:

• Links-modus: Semantisch (A), Hybride (B), of Structuur (C). A bouwt vooral op similarity; B combineert structuur + semantiek; C legt meer nadruk op curriculum‑structuur. Deze keuze wordt in je browser onthouden.
• Layout: Thema/cluster (relaties) of Links→rechts (curriculumvolgorde). Zet “Zwakke chronologie” alleen aan als je sequence‑links bewust wilt laten meewegen.
• Experimenteerpaneel: presets (balanced/baseline/dense/strict) plus sliders voor sim‑parameters (backend) en layout‑physics (frontend). Klik Pas toe om de grafiek opnieuw te laden met die instellingen; Reset zet terug naar het aanbevolen startpunt.

Tip: gebruik de “SIM strength verdeling” grafiek om te zien of je minScore te streng (te weinig links) of te los (te veel ruis) hebt gezet.

4. Kwaliteit & begrijpelijkheid (voor niet-technische reviewers)

Veel problemen zijn inhoudelijk: te grove splitsing, onduidelijke definities, of misplaatste units. Deze sectie geeft heuristieken die je kunt toepassen zonder code.

4.1 Heuristieken

• Definities moeten één concept helder maken, niet een halve pagina tekst.
• Proposities moeten “claim‑vorm” hebben (iets dat waar/onwaar kan zijn).
• Logische punten moeten relaties duidelijk maken (dus niet alleen herhalen).

4.2 Voorbeeld van goed element

5. Privacy & rol van personalisatie (niet-technisch)

FUGA kan personalisatie gebruiken om leren effectiever te maken, maar hoort geen privé‑details te herhalen. Denk aan “abstracte personalisatie”: voorbeelden aansluiten bij interesses zonder identificeerbare gegevens.

5.1 Regels in mensentaal

• Gebruik categorieën (“sport”, “muziek”, “werkcontext”) in plaats van namen en specifieke gebeurtenissen.
• Als een cliënt iets persoonlijks deelt, mag de tutor het gebruiken als context, maar niet als “nieuw geheugenfeit”.
• Stimuleer creative reproduction via metaforen/analogieën, maar toets correctheid.

6. Tutor gedrag (conceptueel, zonder code)

De tutor hoort niet pedant te zijn. Hij moet net genoeg uitleg geven, vaak checken wat de cliënt al weet, en bij hogere mastery meer uitdaging bieden (transfer, analogieën, varianten).

7. Troubleshooting (zonder code)

7.1 Dossier blijft leeg

• Client niet actief: FUGA staat niet aan voor deze cliënt, of er is geen actief project gekozen.
• Nog geen “bruikbare” input: de observe‑pipeline negeert heel korte/lege berichten (minimaal 2 alfanumerieke tekens; “ok” telt dus wel).
• Asynchroon: evidence wordt in de achtergrond verwerkt. Als je net iets testte: ververs na een halve minuut en kijk opnieuw.
• Geen elementen: als ingest weinig/geen elements maakte, is er ook niets om evidence aan te koppelen.

Als het dossier leeg blijft, ligt dat meestal aan één van deze punten:

7.2 Te weinig elements of te lineaire structuur

1. Check of de PDF tekstextractie veel tekst opleverde (soms is PDF een scan).
2. Her-ingest met verbeterde extractie of betere chunking (als beschikbaar).
3. Als units verkeerd zijn: check headings/structuur in de bron (bijv. week‑labels).

Appendix A. Technisch referentie (endpoints & datastroom)

Appendix B. Developer troubleshooting (debug patterns)

Einde NL versie.

FUGA – Admin guide

This guide serves two audiences. Technical parts are marked as TECH and are placed further down. Non‑technical readers can safely skip them.

Terminology: some internal notes may use “VUGA”; in the UI and routes the system is called FUGA. It is the same module.

1. What is FUGA?

FUGA is a curriculum‑tutor module inside GRITT. You ingest curriculum material (often a PDF), FUGA splits it into small elements and relations, and the system can track a client’s understanding over time.

1.1 Goal (one sentence)

FUGA supports learning by breaking a curriculum into “what must be understood”, and linking evidence from conversations to those elements.

1.2 Example (intuitive)

Suppose you upload a PDF “Political philosophy 1950‑present”. Ingest may produce: units per week, containing definitions (meaning of concept X), propositions (claim Y), and logic points (relations/argument structure). When a client later explains “Cohen criticises equality…”, that becomes evidence for relevant elements.

What’s on the FUGA admin page?

This is a quick tour of admin-fuga.html: what each area does and where to find it. The screenshots show the static layout; in production, lists and the graph populate after selecting a project and a client.

Top barnavigation

Right side: Guide and Logout.

1) Client selector + dossierclient settings

• Search + dropdown: select a client, filter by name.
• Refresh: reload the client list.
• FUGA on: whether the client is tracked by FUGA.
• Active project: the dominant curriculum project used for context/matching.
• Save writes settings; Dossier loads mastery + recent evidence.
• Right side: dossier panel + optional Debug (raw JSON).

2) Activity & cluster mapgraph + overlay

• 2D/3D toggle (3D is default).
• Show client activity: overlay on/off.
• Labels: show/hide labels.
• Center resets the camera; Refresh reloads the graph.
• Scope: curriculum/macro/course/unit (choose object when needed).
• Layout: relation-based clustering vs left-to-right curriculum order.
• Weak chronology: lets sequence links slightly influence layout.
• Glow: last activity: highlight where the newest evidence landed.
• Time slider filters the overlay by recency.
• Experiments panel: backend SIM + frontend layout parameters; Apply reloads with new tuning.
• Bottom: SIM-strength histogram, legend, and click-to-inspect details.

Note: if no client is selected, the map can be gated (“Select a client first”). This is intentional.

3) Project selection + files + structuremanagement

• Select a project, refresh, or delete (password-confirmed).
• Download backups (project or all metadata).
• Project documents inventory (per-file actions).
• Structure tree (macro→course→unit) + mapping; includes a structure chat and suggested command flow (dry-run → apply).

4) Upload & ingestinput

• Pick file → upload PDF → ingest.
• Admin (curriculum) vs Client (evidence) mode.
• Progress bar + status chips show ingest state and counts.
• “Needs help” box appears when structure placement is uncertain.

5) Curriculum explorerinspect content

Use this to browse macro/course/unit and load elements for quick quality checks.

6) Testsdiagnostics

• Context test: end-to-end sanity check.
• Vector test: retrieval sanity check.

Pop-ups (modals)

Delete projectpassword confirmation

Delete filepassword confirmation

Text viewerextracted text

2. Concepts (with diagram)

FUGA models a curriculum in layers. In the current implementation the top is usually a project. Optionally, a macro section sits under the project (e.g. “Year 1”), then courses, then units (e.g. weeks), and finally elements (small knowledge items such as definitions, propositions and conclusions).

2.1 Mastery and evidence (example)

Evidence is a concrete “proof item” (typically a quote/snippet) from a client chat or submitted document, which FUGA links to one or more elements. Mastery is the (provisional) level of understanding of an element based on that evidence.

• Sources: chat (client), chat (assistant), and later also “essays/assignments” (via upload).
• What is stored: snippet (verbatim), paraphrase, scores for literal and higher‑order, privacy score (0–10), and optional “contradiction”.
• Scale: mastery is stored as 0–10 internally (i.e. 0–100%); the graph normalises it for colouring.
• Important: not every message is compared to all elements. FUGA uses retrieval → shortlist → LLM judge and stores only relevant evidence.

2.2 Admin overrides (when to use)

Overrides are useful when ingest text is unclear or importance is wrong. Overrides should be auditable and should not corrupt raw ingest output.

3. Admin workflow (no code)

This is the core for non‑technical admins: create project, upload PDF, start ingest, check counts, configure a client.

3.1 What to verify after ingest

• Counts: how many macro sections/courses/units/elements were created?
• Distribution: do weeks/units look sensible (not everything in one unit)?
• Files: does the extracted text look correct when opening a file?
• Analysis report: open “Analysis” on a file and check whether the elements are usable.
• Incidents/structure help: are there “needs help” messages or open incidents?

3.2 Configure a client

Select a client, enable FUGA (enabled), and link an active project. From that moment, chat messages are observed in the background and the dossier can start filling with mastery + evidence.

3.3 File list, scope and per-file analysis

Under “Project documents” each upload shows a row with actions. This is your control point: it’s the bridge between source material and curriculum elements.

• Original: opens the original PDF.
• Text: shows extracted text (useful to spot extraction issues quickly).
• Analysis: opens an analysis report with units + elements. If a client is selected, it also shows that client’s evidence linked to elements.
• Scope: a document can belong at curriculum, macro, course or unit level. Scope can be changed later (admin action).
• Delete: admins can delete a document (with password confirmation). Client uploads may be “locked” to avoid accidental removal.
• PDF (analysis): the analysis view supports printing to PDF for a shareable snapshot.

3.4 Structure & document mapping (tree view)

The “Structure & document mapping” panel shows the taxonomy tree (macro → course → unit) and how files map into it. If FUGA cannot confidently place a new upload during ingest, it creates a needs help incident. You can then:

• run deterministic commands, or
• ask for an AI command suggestion (LLM) and then decide.

Principle: FUGA is allowed to be uncertain, but it must say so explicitly and provide a correctable proposal.

3.5 Cluster map: link mode, layout, and experiments panel

The cluster map is meant to show thematic islands (relation-based clustering) with an optional client‑activity overlay. In the current build, three controls matter most:

• Link mode: Semantic (A), Hybrid (B), or Structure (C). A relies mostly on similarity; B blends structure + semantics; C emphasizes curriculum structure. This choice is stored in the browser.
• Layout: Theme/cluster (relations) or Left→right (curriculum order). Enable “weak chronology” only when you deliberately want sequence links to influence the layout.
• Experiments panel: presets (balanced/baseline/dense/strict) plus sliders for sim parameters (backend) and layout physics (frontend). Click Apply to reload the graph with these settings; Reset returns to the recommended starting point.

Tip: use the “SIM strength distribution” plot to judge whether your minScore is too strict (too few links) or too loose (too much noise).

4. Quality & interpretability (for non-technical reviewers)

Many problems are content-level: overly coarse splitting, unclear definitions, or mis-grouped units. This section gives heuristics you can apply without code.

4.1 Heuristics

• Definitions should clarify one concept, not half a page.
• Propositions should be claim-shaped (true/false in principle).
• Logic points should encode relations (not just repetition).

4.2 Example of a good element

5. Privacy & personalization (non-technical)

FUGA can use personalization to improve learning, but should not repeat private details. Prefer “abstract personalization”: examples aligned with interests without identifiable information.

5.1 Rules in plain language

• Use categories (“sports”, “music”, “work context”) rather than names and specific events.
• If a client shares something personal, the tutor may use it as context but should not treat it as persistent memory.
• Encourage creative reproduction (metaphors/analogies) while checking correctness.

6. Tutor behaviour (conceptual, no code)

The tutor should not be pedantic. It should provide just enough explanation, frequently check what the client already knows, and offer more challenge at higher mastery (transfer, analogies, variants).

7. Troubleshooting (no code)

7.1 Dossier stays empty

• Client not active: FUGA is not enabled for the client, or no active project is selected.
• No usable input yet: the observe pipeline ignores very short/empty messages (minimum 2 alphanumeric characters; “ok” does count).
• Asynchronous: evidence is processed in the background. If you just tested: refresh after ~30 seconds and check again.
• No elements: if ingest created few/no elements, there is nothing to link evidence to.

If the dossier stays empty, it is usually one of these:

7.2 Too few elements or overly linear structure

1. Check whether PDF text extraction produced substantial text (scanned PDFs often do not).
2. Re-ingest with improved extraction or better chunking (if available).
3. If units look wrong: verify source structure (e.g., week headings).

Appendix A. Technical reference (endpoints & data flow)

Appendix B. Developer troubleshooting (debug patterns)

End of EN version.