Digital Humaniora |

tei-mcp v0.3: TEI-kodning utan att skriva om källan

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

När jag var målet att hindra AI-assistenter från att hallucinera TEI-uppmärkning. Schemaförankringen löste en del av problemet: med direkt, verktygsbaserad tillgång till P5-specifikationen behöver modellen inte längre gissa vad ett element betyder eller vilka attribut det tar. Resultatet validerar.

Men hallucinationen har två ansikten i TEI-kodning, och schemat fångar bara det ena. Att validera mot specifikationen säger dig att uppmärkningen är välformad. Det säger inget om den text uppmärkningen omsluter. Och det är där – i själva texten – de mer skadliga hallucinationerna håller till. Spannlåst komposition (span-locked composition), huvudnyheten i v0.3, är utformad just för att förhindra dem.

Innehållsförteckning

Hallucinationen som schemat inte kan fånga

Be en modell koda ett franskt brev från 1500-talet, och du får ofta tillbaka ett TEI-dokument som ser oklanderligt ut. Headern är ifylld, <persName>-taggarna sitter rätt, <dateline> är välformad. Kör det genom validate_document och det går igenom.

Jämför sedan brödtexten med källan.

mesme har blivit même. Ett komma har flyttat på sig. luy har i tysthet moderniserats till lui. En sats som var svårläst i handskriften har ”rättats” till något prydligare. Ingen av ändringarna var begärd. Ingen av dem flaggas. Dokumentet är schemagiltigt och tyst felaktigt.

För ett arkivflöde – där den kodade texten blir den permanenta post som senare läsare, sökindex och citeringar förlitar sig på – är detta den typ av fel som betyder mest. En felformad tagg är irriterande. En moderniserad stavning som ingen upptäcker på fem år är en korruption.

Spannlåst komposition

Den nya versionen (v0.3) levererar en mekanism mot hallucinationer som siktar rakt på just den här typen av fel. Designmålet är att göra hallucinationer i brödtexten omöjliga per konstruktion, inte bara osannolika.

Idén är enkel: modellen skriver aldrig brödtext.

I stället ser arbetsflödet ut så här:

Modellen anropar get_source("letter_001") och får källans råtext som en oföränderlig sträng.
För varje tagg den vill sätta anropar den tag_span("letter_001", start, end, element_path, attrs) – och registrerar därmed ett TEI-element över ett teckenintervall i källan.
När den är klar anropar den compose("letter_001"). Servern flätar in de registrerade taggarna i den ursprungliga råtexten, renderar den färdiga TEI-filen och kontrollerar sedan byte för byte att det renderade dokumentets rena textinnehåll är identiskt med källan.

Stämmer bytena kommer dokumentet tillbaka. Gör de inte det – om modellens taggar på något sätt implicerar en brödtext som avviker från källan med ett enda tecken – kastar compose() ett fel i stället för att returnera ett korrupt dokument.

Det finns ingen väg genom det här arbetsflödet där modellen producerar ett TEI-dokument vars brödtext avviker från källan. Invarianten är mekanisk, inte beteendemässig. Du behöver inte lita på att modellen låter bli att hallucinera; du behöver lita på en ==-jämförelse mellan två bytesträngar.

Vad det är, och vad det inte är

Spannlåst komposition är ett komplement till schemaförankringen, inte en ersättning. Schemaverktygen (validate_document, lookup_element, valid_children och resten av de ursprungliga sexton) hjälper modellen att producera giltig TEI. Spannlåst komposition garanterar att brödtexten inuti den TEI-filen är trogen källan. Ett kodningsflöde som ska kunna tas i drift måste uppfylla båda kraven, och nu täcks båda av en och samma server.

Det är heller inget trollspö som fixar allt. compose() kontrollerar ännu inte att de registrerade taggarna är tillåtna enligt en laddad ODD-anpassning – det kommer i en uppföljning. Registrerade taggar ligger i processminnet och överlever inte en omstart. Och källfilerna måste vara läsbara från den plats där servern körs. Allt detta går att åtgärda; inget av det rubbar den centrala invarianten.

Varför det spelar roll bortom TEI

Mönstret går att generalisera. Varje gång en modell ombeds annotera, omvandla eller omsluta en text – och varje gång textens integritet väger tyngre än modellens förmåga att ”förbättra” den – passar samma slags lösning. Be inte modellen skriva om texten. Be den producera instruktioner över texten, och låt en deterministisk kompositör tillämpa dem under en likhetsinvariant.

För digitala utgåvor i synnerhet förändrar detta vad man med gott samvete kan be en modell om. Kodningen blir med ett slag en uppgift man kan delegera utan att manuellt behöva jämföra varje resultat med källan. Maskinen tar den tråkiga vägen; utgivaren granskar uppmärkningen, inte stavningen.

Hämta uppdateringen

Har du redan tei-mcp installerat:

uvx tei-mcp@latest

Eller från början:

pip install tei-mcp

För att använda spannlåst komposition pekar du servern mot en katalog med källfiler i råtext:

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

Varje fils namnstam blir dess dokument-ID (letter_001.txt → letter_001).

Källkod, fullständig dokumentation och designanteckningarna om invarianten:

En annan sorts digital utgåva

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

De flesta primärkällor blir aldrig utgivna. Den modell vi förlitar oss på för att råda bot på det, anslagsfinansierade digitala utgåvor, är för dyr, för centraliserad och för bräcklig för att fungera i stor skala. Jag har just publicerat som förklarar varför jag bygger den kritiska utgåvan av Cavrianas brev på ett annat sätt: digitaliserade primärkällor som växer organiskt, med minimal infrastruktur och automatiserat underhåll, öppna för samarbete och så billiga att inga anslag ens behövs. Det är ett argument för en digital humaniora som fungerar oavsett institutionellt stöd.

tei-mcp: TEI P5 för AI-agenter

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

Har du någon gång låtit en AI-kodassistent skriva TEI-XML har du nog märkt att den gör fel. Element dyker upp där de inte hör hemma. Attribut hittas på. Nästlingsreglerna ignoreras. Modellen har en ungefärlig känsla för hur TEI ser ut, men ingen tillförlitlig kunskap om specifikationen.

tei-mcp löser det genom att ge AI-agenter direkt, verktygsbaserad tillgång till riktlinjerna för TEI P5.

Innehållsförteckning

Vad är MCP?

(MCP) är en öppen standard som låter AI-applikationer ansluta till externa datakällor och verktyg. Tänk på det som en USB-port för AI: ett enda protokoll som låter vilken kompatibel klient som helst – Claude, Cursor, Windsurf och andra – koppla in sig på specialiserade tjänster.

En MCP-server exponerar verktyg som AI:n kan anropa under ett samtal. I stället för att förlita sig på memorerade träningsdata kan modellen fråga en levande, auktoritativ källa.

Vad tei-mcp gör

tei-mcp tolkar ODD-specifikationen för TEI P5 och exponerar 16 verktyg som täcker de vanligaste frågor en utgivare eller kodare ställer:

Vad är det här elementet? Slå upp vilket element, vilken klass, vilket makro eller vilken modul som helst på namn, med skiftlägesokänslig matchning och förslag vid felstavning.
Vilka attribut tar det? Lös upp attributen genom hela klasshierarkin – lokala attribut först, sedan de ärvda i ordning.
Vad får finnas inuti? Expandera innehållsmodeller till strukturerade träd, eller få en platt lista över giltiga barnelement.
Får det här elementet stå här? Kontrollera nästlingen förälder–barn, eller spåra nåbarheten genom hela elementhierarkin.
Är mitt dokument giltigt? Validera en TEI-XML-fil mot specifikationen: innehållsmodeller, attributvärden, slutna värdelistor, referensintegritet och utfasningsvarningar.
Och mitt projektschema? Ladda en ODD-anpassningsfil för att begränsa allt ovanstående till ditt projekts specifika delmängd av TEI.

Varför det spelar roll

TEI-kodning kräver att man ständigt slår i riktlinjerna. Erfarna kodare har de vanligaste mönstren i ryggmärgen, men även de måste kontrollera specifikationen för mindre bekanta element eller invecklade innehållsmodeller. För AI-assistenter, som inte har någon sådan inövad kunskap, är problemet värre: de hallucinerar fram uppmärkning som ser rimlig ut men är fel.

Med tei-mcp behöver AI:n inte gissa. Den kan slå upp svaret i specifikationen innan den skriver en enda vinkelparentes. Resultatet är uppmärkning som följer TEI P5 – eller ditt projekts ODD-anpassning.

Kom igång

Installera från PyPI:

pip install tei-mcp

Lägg sedan till servern i din MCP-klients konfiguration:

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

Servern laddar ner TEI-specifikationen vid första körningen och fungerar med vilken MCP-kompatibel klient som helst.

Källkod och fullständig dokumentation:

Att lära ut binär kod med ITA2-telegrafemulatorn

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

Att göra det abstrakta gripbart

Den här ITA2-emulatorn är ett handfast hjälpmedel i undervisningen. Genom att göra abstrakta kodningsbegrepp synliga och interaktiva leder den studenterna fram till ett av datorteknikens och telekommunikationens nyckelbegrepp: den binära representationen – hur text blir mönster av ettor och nollor. Det brukar vi lära ut abstrakt, men när hålen faktiskt dyker upp på remsan blir det lättare att begripa hur fysiska system kan bära digital information.

ITA2 (Baudot-Murray) Telegraph Type Emulator

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

Type word:

Historisk bakgrund: från telegraf till dator

Koden ITA2 (International Telegraph Alphabet No. 2), även kallad Baudot–Murray-koden, utvecklades på 1920-talet som en förfining av Émile Baudots ursprungliga telegrafkod från 1870-talet. Dessa tidiga telekommunikationssystem påverkade den senare datorutvecklingen direkt:

Fembitarskodningen var ett tidigt exempel på teckenkodning
Teckenuppsättningens begränsningar (bara 32 möjliga kombinationer med fem bitar) ledde till den sinnrika skiftmekanismen mellan BOKSTÄVER och SIFFROR (LETTERS/FIGURES)
Systemet användes för fjärrskrivare långt in på 1900-talet

Tillståndsmaskiner på lek

Skiftmekanismen mellan BOKSTÄVER och SIFFROR är en naturlig ingång till tillståndsmaskiner. Genom att pröva sig fram upptäcker studenterna att samma mönster kan stå för olika tecken beroende på vilket läge apparaten befinner sig i. Den praktiska erfarenheten av tillståndsberoende kodning förbereder dem för mer avancerade datavetenskapliga begrepp. Bitmönstret 00011 står t.ex. för:

bokstaven ’A’ i BOKSTÄVER-läget
siffran ’1’ i SIFFROR-läget Denna dubbla tolkning, styrd av tillståndet, är grundläggande för hur datorer hanterar data.

Övningar i klassrummet

Några sätt att använda ITA2-emulatorn i undervisningen:

Kodknäckning: låt studenterna avkoda meddelanden skrivna som ITA2-mönster
Effektiv kodning: diskutera varför skiftmekanismen var viktig för att spara bandbredd
Kodningens utveckling: jämför ITA2:s fembitarskod med ASCII (sju bitar) och Unicode
Fysisk databehandling: koppla det historiska systemet till moderna mikrokontroller som Arduino

Tillgänglighet

Bortom det historiska intresset passar det här arbetssättet studenter som lär sig på olika sätt:

den som lär visuellt ser mönstren
den som lär genom att göra griper direkt in i kodningsprocessen
den som tänker i begrepp kan utforska informationsteorins matematiska sida

Teknisk utformning

Emulatorn är skriven i JavaScript och kan enkelt byggas in i vilken webbaserad lärplattform som helst. Koden är modulär och kan anpassas till olika undervisningssammanhang. Källkoden finns här, och där kan du också pröva emulatorn själv: