Umanistica Digitale |

tei-mcp v0.3: codificare in TEI senza riscrivere la fonte

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

Quando ho , lo scopo era impedire agli assistenti IA di allucinare marcatura TEI. L’ancoraggio allo schema ha risolto una parte del problema: con un accesso diretto, per mezzo di strumenti, alla specifica P5, il modello non deve più indovinare che cosa significhi un elemento o quali attributi accetti. L’output passa la validazione.

Ma nella codifica TEI l’allucinazione ha due facce, e lo schema ne coglie una sola. Validare rispetto alla specifica vi dice che la marcatura è ben formata; non dice nulla del testo che quella marcatura racchiude. Ed è lì, nel testo, che si annidano le allucinazioni più dannose. La composizione span-locked, novità di punta della v0.3, è pensata apposta per impedirle.

Indice dei Contenuti

L’allucinazione che lo schema non vede

Chiedete a un modello di codificare una lettera francese del Cinquecento e otterrete spesso un documento TEI dall’aria impeccabile: header compilato, tag <persName> al posto giusto, <dateline> ben formata. Passatelo per validate_document, e passa.

Poi confrontate il corpo con la fonte.

mesme è diventato même. Una virgola è migrata. luy è stato modernizzato in lui senza dir niente a nessuno. Una frase ostica nel manoscritto è stata «corretta» in qualcosa di più pulito. Nessuna di queste modifiche era stata richiesta; nessuna viene segnalata. Il documento è valido per lo schema e sbagliato in silenzio.

In un flusso di lavoro archivistico – dove il testo codificato diventa il documento definitivo su cui contano lettori, indici di ricerca e citazioni – è questo il guasto che conta di più. Un tag malformato è una seccatura; una grafia modernizzata che nessuno nota per cinque anni è una corruzione.

La composizione span-locked

La nuova versione (v0.3) include un meccanismo di prevenzione delle allucinazioni mirato proprio a questo guasto. L’obiettivo di progetto è rendere le allucinazioni nel corpo del testo impossibili per costruzione, non semplicemente improbabili.

L’idea è semplice: il modello non batte mai il corpo del testo.

Il flusso di lavoro, invece, è questo:

Il modello chiama get_source("letter_001") e riceve il testo semplice di partenza come stringa immutabile.
Per ogni tag che vuole applicare, chiama tag_span("letter_001", start, end, element_path, attrs), registrando un elemento TEI su un intervallo di caratteri della fonte.
Quando ha finito, chiama compose("letter_001"). Il server intercala i tag registrati nel testo semplice originale, produce la TEI finale e poi verifica byte per byte che il contenuto testuale piatto del documento prodotto sia uguale alla fonte.

Se i byte coincidono, il documento viene restituito. Se non coincidono – se i tag del modello implicano in qualche modo un corpo che differisce dalla fonte anche di un solo carattere – compose() solleva un’eccezione invece di consegnare un documento corrotto.

Non esiste percorso, in questo flusso, che porti il modello a produrre un documento TEI con un corpo diverso dalla fonte. L’invariante è meccanico, non comportamentale: non dovete fidarvi del modello perché non allucini; dovete fidarvi di un == fra due stringhe di byte.

Che cos’è, e che cosa non è

La composizione span-locked è complementare all’ancoraggio allo schema, non lo sostituisce. Gli strumenti di ancoraggio (validate_document, lookup_element, valid_children e il resto dei sedici originali) aiutano il modello a produrre TEI valida; la composizione span-locked garantisce che il corpo del testo dentro quella TEI sia fedele alla fonte. Un flusso di codifica che si possa mettere in produzione deve soddisfare entrambi gli assi, e ora un solo server li copre tutti e due.

Non è nemmeno la panacea. compose() non verifica ancora che i tag registrati siano ammessi da una personalizzazione ODD caricata: arriverà. I tag registrati vivono nella memoria del processo e non sopravvivono a un riavvio. E i file di partenza devono essere leggibili da dove gira il server. Sono tutte cose risolvibili, e nessuna intacca l’invariante di fondo.

Perché conta, al di là della TEI

Lo schema si generalizza. Ogni volta che si chiede a un modello di annotare, trasformare o incapsulare un testo – e ogni volta che l’integrità di quel testo conta più della capacità del modello di «migliorarlo» – la soluzione ha la stessa forma. Non chiedete al modello di ribattere il testo; chiedetegli istruzioni sul testo, e lasciate che un compositore deterministico le applichi sotto un invariante di uguaglianza.

Per le edizioni digitali, in particolare, questo cambia ciò che si può affidare a un modello senza rimorsi. La codifica diventa d’un tratto un compito delegabile, senza dover confrontare a mano ogni output con la fonte. La macchina fa la parte noiosa; il curatore rivede la marcatura, non l’ortografia.

Come aggiornare

Se avete già tei-mcp:

uvx tei-mcp@latest

Oppure da zero:

pip install tei-mcp

Per usare la composizione span-locked, indicate al server una directory di file di testo semplice:

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

Il nome di ogni file, senza estensione, diventa l’ID del documento (letter_001.txt → letter_001).

Codice sorgente, documentazione completa e note di progetto sull’invariante:

Un’edizione digitale d’altro genere

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

La maggior parte delle fonti primarie non vede mai la luce. Il modello a cui ci affidiamo per rimediare, l’edizione digitale finanziata a bando, è troppo caro, troppo accentrato e troppo fragile per reggere su larga scala. Ho appena pubblicato in cui spiego perché l’edizione critica delle lettere di Cavriana la sto costruendo in un altro modo: fonti primarie digitalizzate che crescono per accumulo, con un’infrastruttura minima e una manutenzione automatica, aperte alla collaborazione e così poco costose da non aver bisogno di alcun finanziamento. È un argomento a favore di un’umanistica digitale che stia in piedi anche senza il sostegno delle istituzioni.

tei-mcp: la TEI P5 per gli agenti IA

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

Chi ha provato a far scrivere XML TEI a un assistente IA per la programmazione sa già come va a finire: sbaglia. Gli elementi spuntano dove non dovrebbero, gli attributi vengono inventati, le regole di annidamento ignorate. Il modello ha un’idea vaga dell’aspetto della TEI, ma nessuna conoscenza affidabile della specifica.

tei-mcp rimedia dando agli agenti IA un accesso diretto, per mezzo di strumenti, alle Guidelines della TEI P5.

Indice dei Contenuti

Che cos’è MCP?

Il (MCP) è uno standard aperto che permette alle applicazioni di IA di collegarsi a fonti di dati e strumenti esterni. Pensate a una porta USB per l’IA: un solo protocollo con cui qualunque client compatibile – Claude, Cursor, Windsurf e altri – si innesta su servizi specializzati.

Un server MCP espone degli strumenti che l’IA può chiamare nel corso di una conversazione. Invece di affidarsi a ciò che ricorda dell’addestramento, il modello interroga una fonte viva e autorevole.

Che cosa fa tei-mcp

tei-mcp analizza la specifica ODD della TEI P5 ed espone 16 strumenti, che rispondono alle domande più comuni di chi cura o codifica un’edizione:

Che cos’è questo elemento? Cerca qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso.
Quali attributi accetta? Risolve gli attributi lungo l’intera gerarchia di classi: prima quelli locali, poi quelli ereditati, in ordine.
Che cosa può contenere? Espande i modelli di contenuto in alberi strutturati, oppure restituisce l’elenco piatto dei figli ammessi.
Questo elemento può stare qui? Verifica l’annidamento genitore-figlio, o segue la raggiungibilità lungo l’intera gerarchia degli elementi.
Il mio documento è valido? Valida un file XML TEI rispetto alla specifica: modelli di contenuto, valori degli attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione.
E lo schema del mio progetto? Carica un file di personalizzazione ODD per restringere tutto quanto sopra al sottoinsieme di TEI proprio del vostro progetto.

Perché conta

Codificare in TEI vuol dire consultare le Guidelines di continuo. I codificatori esperti hanno interiorizzato gli schemi più comuni, ma anche loro devono controllare la specifica per gli elementi meno familiari o per i modelli di contenuto più intricati. Per gli assistenti IA, che di quella conoscenza interiorizzata non hanno nulla, il problema è peggiore: allucinano una marcatura plausibile all’occhio e sbagliata nella sostanza.

Con tei-mcp l’IA non deve più tirare a indovinare: cerca la risposta nella specifica prima di scrivere una sola parentesi angolare. Il risultato è una marcatura conforme alla TEI P5, o alla personalizzazione ODD del vostro progetto.

Per cominciare

Si installa da PyPI:

pip install tei-mcp

Poi lo si aggiunge alla configurazione del client MCP:

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

Al primo avvio il server scarica la specifica TEI; funziona con qualsiasi client compatibile con MCP.

Codice sorgente e documentazione completa:

Insegnare il binario con l’emulatore del telegrafo ITA2

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

Rendere concreto l’astratto

Questo emulatore ITA2 è, prima di tutto, un sussidio didattico. Rende visibile e manipolabile ciò che di solito resta sulla lavagna, e introduce così gli studenti a un’idea cardine dell’informatica e delle telecomunicazioni: la rappresentazione binaria, cioè il modo in cui un testo diventa una sequenza di uno e di zero. Se ne parla quasi sempre in astratto; ma vedere i fori comparire uno dopo l’altro sul nastro fa capire, meglio di qualsiasi spiegazione, come un oggetto fisico possa portare informazione digitale.

ITA2 (Baudot-Murray) Telegraph Type Emulator

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

Type word:

Un po’ di storia: dal telegrafo al calcolatore

Il codice ITA2 (International Telegraph Alphabet No. 2), detto anche codice Baudot-Murray, fu messo a punto negli anni Venti del Novecento come perfezionamento del codice telegrafico ideato da Émile Baudot negli anni Settanta dell’Ottocento. Da questi primi sistemi di telecomunicazione l’informatica ha ereditato parecchio:

la codifica a 5 bit è uno dei primi esempi di codifica dei caratteri;
l’angustia del repertorio (con 5 bit si hanno appena 32 combinazioni) suggerì l’ingegnoso meccanismo di commutazione LETTERS/FIGURES, fra lettere e cifre;
il sistema rimase in servizio sulle telescriventi fino a Novecento inoltrato.

Le macchine a stati, giocando

La commutazione LETTERS/FIGURES è il modo più naturale di introdurre le macchine a stati. Provando e riprovando, gli studenti scoprono da soli che la stessa sequenza di fori significa caratteri diversi a seconda della modalità in cui si trova la macchina; e questa esperienza diretta di una codifica che dipende dallo stato li prepara a nozioni informatiche ben più complesse. La sequenza 00011, per esempio, vale:

la lettera «A» in modalità LETTERS;
la cifra «1» in modalità FIGURES. Questa doppia lettura, che dipende dallo stato, è alla radice stessa del modo in cui i calcolatori trattano i dati.

Attività per la classe

Qualche idea per portare l’emulatore ITA2 in aula:

Decifrazione: far decodificare agli studenti messaggi trasmessi in sequenze ITA2
Codifica efficiente: discutere perché la commutazione fosse tanto preziosa per risparmiare banda
Evoluzione delle codifiche: confrontare i 5 bit dell’ITA2 con i 7 di ASCII e con Unicode
Physical computing: collegare questo sistema d’altri tempi ai microcontrollori di oggi, Arduino in testa

Un vantaggio per l’accessibilità

Interesse storico a parte, l’approccio viene incontro a studenti che imparano in modi diversi:

chi apprende con gli occhi vede le sequenze;
chi apprende con le mani interviene direttamente sul processo di codifica;
chi ha un’inclinazione teorica può spingersi fino agli aspetti matematici della teoria dell’informazione.

Note tecniche

L’emulatore è scritto in JavaScript e si integra senza fatica in qualunque piattaforma didattica basata sul web. Il codice è modulare e si lascia adattare a contesti d’insegnamento diversi. Il codice sorgente, con l’emulatore da provare, è qui: