Digital Humanities |

tei-mcp v0.3: TEI coderen zonder de bron te herschrijven

Tue, 05 May 2026 00:00:00 +0000

Toen ik , was het doel te voorkomen dat AI-assistenten TEI-markup hallucineren. Schemaverankering loste een deel van het probleem op: met rechtstreekse, op tools gebaseerde toegang tot de P5-specificatie hoeft het model niet langer te raden wat een element betekent of welke attributen het aanvaardt. De uitvoer valideert.

Maar hallucinatie heeft bij TEI-codering twee gezichten, en het schema vangt er maar één van op. Validatie tegen de specificatie vertelt je dat de markup welgevormd is. Ze zegt niets over de tekst die de markup omsluit. En juist daar – in de tekst zelf – schuilen de schadelijkste hallucinaties. Span-locked composition, het paradepaardje van v0.3, is speciaal ontworpen om die te voorkomen.

Inhoudsopgave

De hallucinatie die het schema niet kan vangen

Vraag een model een zestiende-eeuwse Franse brief te coderen en je krijgt vaak een TEI-document terug dat er onberispelijk uitziet. De header is ingevuld, de <persName>-tags staan op de juiste plaats, de <dateline> is welgevormd. Haal het door validate_document en het slaagt.

Vergelijk dan de lopende tekst met de bron.

mesme is même geworden. Een komma is verhuisd. luy is stilzwijgend gemoderniseerd tot lui. Een zinsdeel dat in het handschrift moeilijk leesbaar was, is “verbeterd” tot iets netters. Om geen van die wijzigingen is gevraagd. Geen ervan wordt gemeld. Het document is schemageldig en in alle stilte fout.

Voor een archivistische workflow – waarin de gecodeerde tekst de blijvende versie wordt waarop latere lezers, zoekindexen en citaties vertrouwen – is dit de faalwijze die er het meest toe doet. Een misvormde tag is vervelend. Een gemoderniseerde spelling die vijf jaar lang niemand opmerkt, is een corruptie.

Span-locked composition

De nieuwe versie (v0.3) bevat een mechanisme tegen hallucinaties dat precies op deze faalwijze mikt. Het ontwerpdoel is hallucinaties in de lopende tekst per constructie onmogelijk te maken, niet alleen onwaarschijnlijk.

Het idee is eenvoudig: het model typt nooit lopende tekst.

De workflow ziet er in plaats daarvan zo uit:

Het model roept get_source("letter_001") aan en ontvangt de platte brontekst als onveranderlijke string.
Voor elke tag die het wil aanbrengen, roept het tag_span("letter_001", start, end, element_path, attrs) aan – het registreert daarmee een TEI-element op een tekenbereik in de bron.
Is het klaar, dan roept het compose("letter_001") aan. De server vlecht de geregistreerde tags door de oorspronkelijke platte tekst, rendert de definitieve TEI en controleert vervolgens byte voor byte of de platte tekstinhoud van het gerenderde document gelijk is aan de bron.

Komen de bytes overeen, dan komt het document terug. Zo niet – als de tags van het model op een of andere manier een lopende tekst impliceren die ook maar één teken van de bron afwijkt – dan werpt compose() een fout op in plaats van een corrupt document terug te geven.

Er is geen route door deze workflow waarlangs het model een TEI-document produceert waarvan de lopende tekst van de bron afwijkt. De invariant is mechanisch, niet gedragsmatig. Je hoeft er niet op te vertrouwen dat het model niet hallucineert; je hoeft alleen te vertrouwen op een ==-vergelijking tussen twee bytestrings.

Wat dit is, en wat het niet is

Span-locked composition is een aanvulling op schemaverankering, geen vervanging ervan. De tools voor schemaverankering (validate_document, lookup_element, valid_children en de rest van de oorspronkelijke zestien) helpen het model geldige TEI te produceren. Span-locked composition garandeert dat de lopende tekst binnen die TEI trouw is aan de bron. Een inzetbare codeerworkflow moet aan beide eisen voldoen, en nu dekt één server ze allebei.

Het is ook geen wondermiddel voor alles. compose() controleert nog niet of de geregistreerde tags toelaatbaar zijn volgens een geladen ODD-customisatie – dat komt later. Geregistreerde tags leven in het procesgeheugen en overleven een herstart niet. En de bronbestanden moeten leesbaar zijn vanaf de plek waar de server draait. Dat valt allemaal op te lossen; niets ervan ondergraaft de kerninvariant.

Waarom dit verder reikt dan TEI

Het patroon laat zich veralgemenen. Telkens wanneer een model wordt gevraagd een stuk tekst te annoteren, te transformeren of te omsluiten – en telkens wanneer de integriteit van de onderliggende tekst zwaarder weegt dan het vermogen van het model om die te “verbeteren” – past dezelfde vorm van oplossing. Vraag het model niet de tekst over te typen. Vraag het instructies over de tekst te produceren, en laat een deterministische composer die toepassen onder een gelijkheidsinvariant.

Voor digitale edities in het bijzonder verandert dit wat je een model verantwoord kunt vragen. Coderen wordt ineens een taak die je kunt delegeren zonder elke uitvoer handmatig met de bron te hoeven vergelijken. De machine neemt de saaie weg; de editeur beoordeelt de markup, niet de spelling.

De update ophalen

Heb je tei-mcp al geïnstalleerd:

uvx tei-mcp@latest

Of bij een nieuwe installatie:

pip install tei-mcp

Om span-locked composition te gebruiken, wijs je de server naar een map met platte bronbestanden:

export TEI_MCP_SPAN_SOURCE_ROOT=/path/to/sources
uvx tei-mcp

De naam van elk bestand (zonder extensie) wordt zijn document-ID (letter_001.txt → letter_001).

Broncode, volledige documentatie en de ontwerpnotities bij de invariant:

Een ander soort digitale editie

Tue, 24 Mar 2026 00:00:00 +0000

De meeste primaire bronnen worden nooit gepubliceerd. Het model waarop we vertrouwen om daar iets aan te doen – de gesubsidieerde digitale editie – is te duur, te gecentraliseerd en te kwetsbaar om op grote schaal te werken. Ik heb zojuist gepubliceerd waarin ik uitleg waarom ik de kritische editie van Cavriana’s brieven anders opbouw: gedigitaliseerde primaire bronnen die organisch groeien, met minimale infrastructuur, geautomatiseerd onderhoud, open voor samenwerking, en zo goedkoop dat er niet eens subsidies voor nodig zijn. Het is een pleidooi voor een soort digital humanities dat werkt, met of zonder institutionele steun.

tei-mcp: TEI P5 voor AI-agents

Sun, 15 Mar 2026 00:00:00 +0000

Wie ooit een AI-codeerassistent TEI-XML heeft laten schrijven, heeft het vast gemerkt: het gaat mis. Elementen duiken op waar ze niet horen. Attributen worden verzonnen. Nestingregels worden genegeerd. Het model heeft een ruw idee van hoe TEI eruitziet, maar geen betrouwbare kennis van de specificatie.

tei-mcp lost dat op door AI-agents rechtstreeks, via tools, toegang te geven tot de TEI P5 Guidelines.

Inhoudsopgave

Wat is MCP?

Het (MCP) is een open standaard waarmee AI-toepassingen verbinding kunnen maken met externe gegevensbronnen en tools. Zie het als een USB-poort voor AI: één protocol waarmee elke compatibele client – Claude, Cursor, Windsurf en andere – op gespecialiseerde diensten kan aansluiten.

Een MCP-server stelt tools beschikbaar die de AI tijdens een gesprek kan aanroepen. In plaats van te vertrouwen op uit het hoofd geleerde trainingsdata kan het model een actuele, gezaghebbende bron bevragen.

Wat tei-mcp doet

tei-mcp parseert de ODD-specificatie van TEI P5 en biedt 16 tools aan die de meest voorkomende vragen van een editeur of encoder beantwoorden:

Wat is dit element? Zoek elk element, elke klasse, macro of module op naam op, hoofdletterongevoelig en met suggesties bij tikfouten.
Welke attributen neemt het? Los attributen op over de hele klassenhiërarchie – eerst de lokale, dan de geërfde, in volgorde.
Wat mag erin? Klap inhoudsmodellen uit tot gestructureerde bomen, of vraag een platte lijst van geldige kinderen op.
Mag dit element hier staan? Controleer de nesting van ouder en kind, of volg de bereikbaarheid door de volledige elementenhiërarchie.
Is mijn document geldig? Valideer een TEI-XML-bestand tegen de specificatie: inhoudsmodellen, attribuutwaarden, gesloten waardelijsten, referentie-integriteit en waarschuwingen bij verouderde elementen.
En mijn projectschema? Laad een ODD-customisatiebestand om dit alles te beperken tot de specifieke TEI-deelverzameling van je project.

Waarom het ertoe doet

TEI-codering vereist dat je voortdurend de Guidelines raadpleegt. Ervaren encoders kennen de gangbaarste patronen uit het hoofd, maar zelfs zij moeten de specificatie erbij nemen voor minder vertrouwde elementen of ingewikkelde inhoudsmodellen. Voor AI-assistenten, die zulke verinnerlijkte kennis niet hebben, is het probleem erger: ze hallucineren markup die er plausibel uitziet maar niet klopt.

Met tei-mcp hoeft de AI niet te gokken. Het kan het antwoord in de specificatie opzoeken voordat het één punthaak schrijft. Het resultaat is markup die voldoet aan TEI P5 – of aan de ODD-customisatie van je project.

Aan de slag

Installeer vanaf PyPI:

pip install tei-mcp

Voeg de server daarna toe aan de configuratie van je MCP-client:

{
 "mcpServers": {
 "tei": {
 "command": "uvx",
 "args": ["tei-mcp"]
 }
 }
}

De server downloadt de TEI-specificatie bij de eerste start en werkt met elke MCP-compatibele client.

Broncode en volledige documentatie:

Binaire codering onderwijzen met de ITA2-telegraafemulator

Thu, 13 Feb 2025 00:00:00 +0000

Abstracte begrippen tastbaar maken

Deze ITA2-emulator is een praktisch hulpmiddel voor de les. Door abstracte coderingsbegrippen zichtbaar en interactief te maken, laat hij studenten kennismaken met een kernbegrip uit de informatica en de telecommunicatie: de binaire voorstelling – hoe tekst verandert in patronen van enen en nullen. Meestal onderwijzen we dat abstract; wie de gaatjes daadwerkelijk ziet verschijnen, begrijpt beter hoe een fysiek systeem digitale informatie kan weergeven.

ITA2 (Baudot-Murray) Telegraph Type Emulator

Type a word in the input below to see its representation on the ITA2 tape.

Type word:

Historische context: van telegraaf tot computer

De ITA2-code (International Telegraph Alphabet No. 2), ook bekend als de Baudot-Murray-code, werd in de jaren twintig van de vorige eeuw ontwikkeld als verfijning van de oorspronkelijke telegraafcode van Émile Baudot uit de jaren 1870. Deze vroege telecommunicatiesystemen hebben de latere ontwikkeling van de computer rechtstreeks beïnvloed:

De vijfbitscodering was een vroeg voorbeeld van tekencodering
De beperkte tekenset (met vijf bits zijn maar 32 combinaties mogelijk) leidde tot het vernuftige LETTERS/FIGURES-schakelmechanisme
Het systeem bleef tot ver in de twintigste eeuw in gebruik voor telexapparaten

Toestandsmachines leren door te spelen

Het LETTERS/FIGURES-schakelmechanisme is een natuurlijke inleiding tot toestandsmachines. Studenten ontdekken al experimenterend dat hetzelfde patroon verschillende tekens kan voorstellen, afhankelijk van de actieve modus. Wie zo hands-on ervaring opdoet met toestandsafhankelijke codering, is beter voorbereid op ingewikkelder concepten uit de informatica. Het bitpatroon 00011 staat bijvoorbeeld voor:

de letter ‘A’ in de LETTERS-modus
het cijfer ‘1’ in de FIGURES-modus Deze dubbele lezing, afhankelijk van de toestand, ligt aan de basis van hoe computers met gegevens omgaan.

Lesactiviteiten

Enkele manieren om de ITA2-emulator in het onderwijs in te zetten:

Codekraken: laat studenten berichten ontcijferen die als ITA2-patronen zijn gecodeerd
Zuinig coderen: bespreek waarom het schakelmechanisme belangrijk was om bandbreedte te sparen
Evolutie van de codering: vergelijk de vijfbitscode van ITA2 met ASCII (7 bits) en Unicode
Physical computing: leg het verband tussen dit historische systeem en moderne microcontrollers zoals Arduino

Winst voor de toegankelijkheid

Los van het historische belang komt deze aanpak tegemoet aan uiteenlopende leerstijlen:

visueel ingestelde studenten zien de patronen
wie al doende leert, grijpt rechtstreeks in het coderingsproces in
conceptuele denkers kunnen de wiskundige kant van de informatietheorie verkennen

Technische details

De emulator is geschreven in JavaScript en laat zich eenvoudig in elk webgebaseerd leerplatform inbouwen. De code is modulair en kan aan verschillende onderwijscontexten worden aangepast. De broncode vind je hier, en je kunt de emulator er meteen zelf uitproberen: