TEI |

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:

tei-mcp

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

tei-mcp: la TEI P5 per gli agenti IA

tei-mcp è un server open source che dà agli assistenti IA per la programmazione un accesso diretto alla specifica . Invece di affidarsi a ciò che ricorda dell’addestramento – da cui esce spesso una marcatura plausibile ma sbagliata – l’IA interroga la specifica in tempo reale.

Funzionalità

Il server analizza l’ODD della TEI P5 ed espone 16 strumenti:

Ricerca di qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso
Risoluzione degli attributi lungo l’intera gerarchia di classi TEI (locali ed ereditati)
Espansione dei modelli di contenuto in alberi strutturati, con risoluzione di classi e macro
Verifica dell’annidamento: rapporto diretto genitore-figlio, o raggiungibilità ricorsiva con tracciamento del percorso
Validazione dei documenti rispetto alla TEI P5: modelli di contenuto, attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione
Validazione di singoli elementi per chi lavora per ritocchi successivi
Caricamento di personalizzazioni ODD per restringere lo schema al sottoinsieme proprio di un progetto
Ricerca in tutti i tipi di entità con espressioni regolari

Installazione

pip install tei-mcp

Oppure si esegue direttamente con:

uvx tei-mcp

Uso

Si aggiunge a qualsiasi client compatibile con MCP (Claude, Cursor, Windsurf ecc.):

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

Il codice sorgente e la documentazione sono nel .

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:

Multi-Saxon

Fri, 28 Mar 2025 00:00:00 +0000

Multi-Saxon: trasformazioni XSLT in parallelo per grandi corpora TEI

Multi-Saxon colma una lacuna seria fra gli strumenti di elaborazione XML: esegue in parallelo trasformazioni XSLT 2.0 e 3.0 che LXML, la diffusa libreria XML per Python, non sa gestire. Pensato per grandi collezioni di documenti XML TEI, abbatte i tempi di elaborazione grazie a un’esecuzione parallela efficiente.

Caratteristiche principali

XSLT avanzato: elabora trasformazioni XSLT 2.0 e 3.0, fuori dalla portata di LXML
Elaborazione parallela: la parallelizzazione riduce drasticamente i tempi di trasformazione delle grandi collezioni di documenti
Su misura per la TEI: progettato apposta per i documenti XML della Text Encoding Initiative (TEI)
Prestazioni scalabili: gestisce con efficienza corpora da centinaia a migliaia di documenti
Multipiattaforma: funziona su sistemi operativi e ambienti diversi

Il problema che Multi-Saxon risolve

Chi lavora con la TEI nell’umanistica digitale si scontra spesso con due ostacoli:

LXML (una comune libreria Python per l’elaborazione XML) sostiene soltanto XSLT 1.0, e preclude quindi le funzionalità più avanzate di XSLT 2.0/3.0
Elaborare in sequenza grandi corpora di documenti TEI può richiedere tempi proibitivi

Multi-Saxon risponde a entrambi sfruttando le capacità XSLT avanzate di Saxon e distribuendo l’elaborazione su più core, con guadagni di prestazioni notevoli.

Realizzazione

Multi-Saxon accoppia Python al processore Saxon per Java in una pipeline di trasformazione ad alte prestazioni:

usa la libreria Saxon per Java per un’elaborazione XSLT 2.0/3.0 robusta
ricorre al multiprocessing per distribuire le trasformazioni sui core disponibili
gestisce con efficienza i pool di processi per massimizzare il throughput
offre un’interfaccia semplice per l’elaborazione in batch dei documenti TEI

Esempio d’uso

from multi_saxon import MultiSaxon

# Initialize with your XSLT stylesheet
transformer = MultiSaxon("transform.xsl")

# Transform a single document
transformer.transform("input.xml", "output.xml")

# Transform an entire directory in parallel
transformer.transform_directory("input_dir", "output_dir")

Che cosa cambia per l’umanistica digitale

Per i progetti di umanistica digitale alle prese con grandi collezioni di documenti TEI, Multi-Saxon rende possibili:

trasformazioni complesse sull’intero corpus, impensabili con LXML
tempi di elaborazione drasticamente ridotti (spesso di 5-10 volte sui sistemi multi-core)
analisi più sofisticate grazie alle funzionalità avanzate di XSLT 2.0/3.0
un flusso di lavoro più semplice per elaborare intere collezioni di documenti

Il codice sorgente e la documentazione sono nel .

persNamer

Fri, 28 Mar 2025 00:00:00 +0000

persNamer: collegare la TEI al Virtual International Authority File

persNamer è uno strumento Python specializzato che facilita l’integrazione, nei documenti XML TEI, dei dati di autorità sulle persone forniti da VIAF (Virtual International Authority File). Convertendo gli identificatori VIAF in marcatura TEI pronta all’uso, riduce di molto il lavoro manuale necessario per creare voci di persona strutturate in un’edizione critica digitale.

Il controllo di autorità nella TEI

Le edizioni critiche digitali richiedono spesso di identificare con precisione i personaggi storici, con i nomi normalizzati e le date di nascita e di morte. Mantenere un controllo di autorità coerente in tutto un progetto richiede di:

identificare le persone nei testi storici
trovare dati autorevoli su di loro
creare voci TEI formattate a dovere
garantire riferimenti coerenti in tutto il progetto

Passaggi che, di norma, sono manuali, lenti e soggetti a incoerenze.

Come funziona persNamer

persNamer automatizza questo flusso di lavoro:

Recupero dei dati VIAF: dato un identificatore VIAF, lo strumento recupera i dati RDF tramite negoziazione del contenuto HTTP
Estrazione delle informazioni essenziali: analizza l’RDF per estrarre il nome preferito, la data di nascita e la data di morte
Generazione della marcatura TEI: crea due frammenti XML:
- una voce dell’authority file (elemento <person> con un xml:id generato, <persName>, <birth>, <death> e <idno type="VIAF">)
- un tag di annotazione a parte (<persName> con un attributo ref che rimanda alla voce di autorità)

Questo doppio output permette ai curatori di mantenere un authority file centralizzato e, insieme, di inserire con facilità i tag di annotazione nei loro testi TEI.

Caratteristiche principali

Generazione normalizzata degli ID: crea ID XML coerenti nella forma pers-[cognome]-[iniziale del nome] (per es. pers-deteligny-c)
Analisi RDF: usa rdflib per estrarre le informazioni da diverse proprietà RDF (per es. rdfs:label, schema:name, viaf:mainHead)
Interfaccia a riga di comando: si esegue con un numero VIAF come unico argomento obbligatorio
Output dettagliato: accompagna l’XML finale con informazioni dettagliate sull’elaborazione

Esempio d’uso

python persNamer.py 314802260

Questo comando produce:

<person xml:id="pers-deteligny-c">
 <persName>Charles deTéligny</persName>
 <birth>1535</birth>
 <death>1572-08-24</death>
 <idno type="VIAF">314802260</idno>
</person>

<persName ref="#pers-deteligny-c">Charles deTéligny</persName>

Applicazioni nell’umanistica digitale

persNamer torna particolarmente utile per:

le edizioni critiche digitali che richiedono un controllo di autorità
i progetti di codifica TEI che trattano personaggi storici
le iniziative di linked data che collegano documenti a record di autorità
garantire la coerenza in grandi corpora TEI
insegnare il controllo di autorità nei corsi di umanistica digitale

Realizzazione

persNamer è scritto in Python e dipende da:

requests per le richieste HTTP
rdflib per l’analisi RDF
lxml per la gestione dell’XML

Il codice sorgente e la documentazione sono nel .