TEI |

tei-mcp v0.3: codificar en TEI sense reescriure la font

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

Quan , l’objectiu era evitar que els assistents d’IA al·lucinessin marcatge TEI. L’ancoratge a l’esquema en va resoldre una part: amb accés directe, mitjançant eines, a l’especificació P5, el model ja no ha d’endevinar què significa un element ni quins atributs accepta. El resultat valida.

Però en la codificació TEI l’al·lucinació té dues cares, i l’esquema només n’atrapa una. Validar contra l’especificació et diu que el marcatge està ben format. No diu res del text que aquest marcatge embolcalla. I és allà – en el text mateix – on viuen les al·lucinacions més perjudicials. La composició per intervals blocats (span-locked composition), la novetat estrella de la v0.3, està dissenyada precisament per evitar-les.

Index

L’al·lucinació que l’esquema no pot atrapar

Demana a un model que codifiqui una carta francesa del segle XVI i sovint et tornarà un document TEI d’aspecte impecable. La capçalera és plena, les etiquetes <persName> són al lloc correcte, el <dateline> està ben format. Passa’l per validate_document i el supera.

Després compara el cos amb la font.

mesme s’ha convertit en même. Una coma ha emigrat. luy s’ha modernitzat silenciosament en lui. Una frase difícil de llegir al manuscrit ha estat «corregida» cap a alguna cosa més neta. Cap d’aquests canvis no s’havia demanat. Cap no està assenyalat. El document és vàlid segons l’esquema i discretament erroni.

En un flux de treball arxivístic – on el text codificat esdevé el registre permanent de què depenen els lectors, els índexs de cerca i les citacions – aquest és el mode de fallada que més importa. Una etiqueta mal formada és una molèstia. Una grafia modernitzada que ningú no detecta durant cinc anys és una corrupció.

La composició per intervals blocats

La nova versió (v0.3) incorpora un mecanisme de prevenció d’al·lucinacions que apunta directament a aquest mode de fallada. L’objectiu de disseny és fer que les al·lucinacions en el cos del text siguin impossibles per construcció, no merament improbables.

La idea és senzilla: el model no escriu mai el cos del text.

En lloc d’això, el flux de treball és el següent:

El model crida get_source("letter_001") i rep el text pla de la font com una cadena immutable.
Per a cada etiqueta que vol aplicar, crida tag_span("letter_001", start, end, element_path, attrs), i registra així un element TEI sobre un interval de caràcters de la font.
Quan ha acabat, crida compose("letter_001"). El servidor intercala les etiquetes registrades amb el text pla original, genera la TEI final i, tot seguit, verifica byte a byte que el contingut textual pla del document generat és igual a la font.

Si els bytes coincideixen, el document es retorna. Si no – si les etiquetes del model impliquen d’alguna manera un cos que difereix de la font encara que sigui en un sol caràcter –, compose() llança un error en lloc de retornar un document corromput.

No hi ha cap camí en aquest flux de treball pel qual el model produeixi un document TEI amb un cos de text diferent de la font. L’invariant és mecànic, no conductual. No cal confiar que el model no al·lucini; cal confiar en una comprovació == entre dues cadenes de bytes.

Què és, i què no és

La composició per intervals blocats és complementària de l’ancoratge a l’esquema, no el substitueix. Les eines d’ancoratge a l’esquema (validate_document, lookup_element, valid_children i la resta de les setze originals) ajuden el model a produir una TEI vàlida. La composició per intervals blocats garanteix que el cos del text dins d’aquesta TEI és fidel a la font. Un flux de codificació apte per al desplegament ha de satisfer tots dos eixos, i ara un sol servidor els cobreix tots dos.

Tampoc no és una vareta màgica que ho arregli tot. compose() encara no comprova que les etiquetes registrades siguin admissibles segons una personalització ODD carregada: això vindrà més endavant. Les etiquetes registrades viuen a la memòria del procés i no sobreviuen a un reinici. I els fitxers font han de ser llegibles des d’allà on s’executa el servidor. Tot això té solució; res d’això no soscava l’invariant central.

Per què importa més enllà de la TEI

El patró es generalitza. Sempre que es demana a un model que anoti, transformi o embolcalli un fragment de text – i sempre que la integritat del text subjacent importa més que la capacitat del model per «millorar-lo» – s’hi aplica la mateixa forma de solució. No demanis al model que torni a teclejar el text. Demana-li que produeixi instruccions sobre el text, i deixa que un compositor determinista les apliqui sota un invariant d’igualtat.

Per a les edicions digitals en concret, això canvia el que es pot demanar responsablement a un model. La codificació esdevé de cop una tasca que es pot delegar sense haver de comparar manualment cada resultat amb la font. La màquina fa el camí avorrit; l’editor revisa el marcatge, no l’ortografia.

Obtenir l’actualització

Si ja tens tei-mcp instal·lat:

uvx tei-mcp@latest

O bé, des de zero:

pip install tei-mcp

Per fer servir la composició per intervals blocats, apunta el servidor a un directori de fitxers font en text pla:

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

El nom de cada fitxer, sense l’extensió, esdevé l’identificador del document (letter_001.txt → letter_001).

Codi font, documentació completa i notes de disseny de l’invariant:

tei-mcp

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

tei-mcp: la TEI P5 per als agents d’IA

tei-mcp és un servidor de codi obert que dona als assistents de programació amb IA accés directe a l’especificació . En lloc de refiar-se del que recorda de l’entrenament – cosa que sovint produeix un marcatge plausible però incorrecte –, la IA pot consultar l’especificació en temps real.

Funcions

El servidor analitza l’ODD de la TEI P5 i exposa 16 eines:

Consultar qualsevol element, classe, macro o mòdul pel nom, sense distingir majúscules i amb suggeriments en cas d’errata
Resoldre atributs al llarg de tota la jerarquia de classes de la TEI (locals i heretats)
Expandir models de contingut en arbres estructurats, amb resolució de classes i macros
Validar la imbricació – relació directa pare-fill o accessibilitat recursiva, amb seguiment del camí
Validar documents segons la TEI P5: models de contingut, atributs, llistes de valors tancades, integritat de les referències i avisos d’obsolescència
Validar elements individuals per a fluxos d’edició incremental
Carregar personalitzacions ODD per restringir l’esquema al subconjunt propi d’un projecte
Cercar en tots els tipus d’entitat amb expressions regulars

Instal·lació

pip install tei-mcp

O bé executar-lo directament amb:

uvx tei-mcp

Ús

Afegeix-lo a qualsevol client compatible amb MCP (Claude, Cursor, Windsurf, etc.):

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

El codi font i la documentació són al .

tei-mcp: la TEI P5 per als agents d’IA

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

Qui hagi fet servir un assistent de programació amb IA per escriure XML TEI probablement s’haurà adonat que s’equivoca. Apareixen elements on no toca. S’inventen atributs. Les regles d’imbricació s’ignoren. El model té una idea aproximada de quin aspecte té la TEI, però cap coneixement fiable de l’especificació.

tei-mcp ho resol donant als agents d’IA un accés directe, mitjançant eines, a les directrius de la TEI P5.

Index

Què és MCP?

El (MCP) és un estàndard obert que permet a les aplicacions d’IA connectar-se a fonts de dades i eines externes. Pensa-hi com en un port USB per a la IA: un únic protocol amb què qualsevol client compatible – Claude, Cursor, Windsurf i d’altres – pot endollar-se a serveis especialitzats.

Un servidor MCP exposa eines que la IA pot invocar durant una conversa. En lloc de refiar-se de les dades d’entrenament memoritzades, el model pot consultar una font viva i autoritzada.

Què fa tei-mcp

tei-mcp analitza l’especificació ODD de la TEI P5 i exposa 16 eines que cobreixen les preguntes més habituals que es faria un editor o un codificador:

Què és aquest element? Consulta qualsevol element, classe, macro o mòdul pel nom, sense distingir majúscules i amb suggeriments en cas d’errata.
Quins atributs admet? Resol els atributs al llarg de tota la jerarquia de classes: primer els locals, després els heretats, per ordre.
Què hi pot anar a dins? Expandeix els models de contingut en arbres estructurats, o obtén una llista plana de fills vàlids.
Aquest element pot anar aquí? Comprova la imbricació pare-fill, o traça l’accessibilitat a través de tota la jerarquia d’elements.
El meu document és vàlid? Valida un fitxer XML TEI segons l’especificació: models de contingut, valors d’atribut, llistes de valors tancades, integritat de les referències i avisos d’obsolescència.
I l’esquema del meu projecte? Carrega un fitxer de personalització ODD per restringir tot l’anterior al subconjunt específic de la TEI que fa servir el teu projecte.

Per què importa

Codificar en TEI exigeix consultar constantment les directrius. Els codificadors experimentats interioritzen els patrons més comuns, però fins i tot ells han de comprovar l’especificació quan es tracta d’elements menys familiars o de models de contingut complexos. Per als assistents d’IA, que no tenen cap coneixement interioritzat d’aquesta mena, el problema és pitjor: al·lucinen un marcatge d’aparença plausible però incorrecte.

Amb tei-mcp, la IA no ha d’endevinar res. Pot buscar la resposta a l’especificació abans d’escriure ni un sol parèntesi angular. El resultat és un marcatge conforme a la TEI P5, o a la personalització ODD del teu projecte.

Per començar

Instal·la’l des de PyPI:

pip install tei-mcp

Després, afegeix-lo a la configuració del teu client MCP:

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

El servidor descarrega l’especificació de la TEI la primera vegada que s’executa i funciona amb qualsevol client compatible amb MCP.

Codi font i documentació completa:

Multi-Saxon

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

Multi-Saxon: processament XSLT en paral·lel per a grans corpus TEI

Multi-Saxon cobreix un buit important en les eines de processament XML: permet executar en paral·lel transformacions XSLT 2.0 i 3.0 que LXML (una biblioteca XML molt popular en Python) no pot gestionar. Dissenyat expressament per a grans col·leccions de documents XML TEI, Multi-Saxon accelera notablement el processament gràcies a una execució paral·lela eficient.

Característiques principals

Suport XSLT avançat: processa transformacions XSLT 2.0 i 3.0 fora de l’abast de LXML
Processament en paral·lel: redueix dràsticament el temps de transformació de grans col·leccions de documents gràcies a la paral·lelització
Optimitzat per a TEI: dissenyat específicament per a documents XML de la Text Encoding Initiative (TEI)
Rendiment escalable: gestiona amb eficiència corpus de centenars a milers de documents
Multiplataforma: funciona en sistemes operatius i entorns diversos

El problema que resol Multi-Saxon

Els investigadors en humanitats digitals que treballen amb TEI topen sovint amb dos obstacles importants:

LXML (una biblioteca habitual de processament XML en Python) només admet XSLT 1.0, cosa que impedeix fer servir les funcions més avançades d’XSLT 2.0/3.0
Processar seqüencialment grans corpus de documents TEI pot ser prohibitivament lent

Multi-Saxon resol tots dos problemes aprofitant les capacitats XSLT avançades de Saxon i repartint el processament entre diversos nuclis, amb guanys de rendiment considerables.

Implementació

Multi-Saxon combina Python amb el processador Saxon de Java per crear un flux de transformació d’alt rendiment:

Fa servir la biblioteca Saxon de Java per a un processament robust d’XSLT 2.0/3.0
Implementa el multiprocessament per distribuir les transformacions entre els nuclis de CPU disponibles
Gestiona eficientment els grups de processos per maximitzar el rendiment
Ofereix una interfície senzilla per processar documents TEI per lots

Exemple d’ús

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")

Impacte per a les humanitats digitals

Per als projectes d’humanitats digitals que treballen amb grans col·leccions de documents TEI, Multi-Saxon fa possible:

Transformacions complexes a escala de tot el corpus que serien impossibles amb LXML
Temps de processament dràsticament reduïts (sovint entre 5 i 10 vegades més ràpid en sistemes multinucli)
Anàlisis més sofisticades gràcies a les funcions avançades d’XSLT 2.0/3.0
Un flux de treball més senzill per processar col·leccions senceres de documents

El codi font i la documentació són al .

persNamer

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

persNamer: connectar la TEI amb el Virtual International Authority File

persNamer és una eina especialitzada en Python que facilita la integració en documents TEI XML de dades d’autoritat sobre persones procedents del VIAF (Virtual International Authority File). En convertir els identificadors VIAF en marcatge TEI a punt per fer servir, persNamer redueix notablement la feina manual que comporta crear entrades de persona estructurades per a les edicions acadèmiques digitals.

El repte del control d’autoritats en TEI

Les edicions acadèmiques digitals sovint exigeixen identificar amb precisió els personatges històrics, incloent-hi els seus noms normalitzats i les dates de naixement i mort. Mantenir un control d’autoritats coherent en tot un projecte requereix:

Identificar les persones en els textos històrics
Trobar-ne dades d’autoritat
Crear entrades TEI correctament formatades
Garantir referències coherents al llarg de tot el projecte

Aquests passos solen ser manuals, lents i propensos a la incoherència.

Com funciona persNamer

persNamer automatitza aquest flux de treball:

Obté les dades del VIAF: a partir d’un identificador VIAF, l’eina recupera les dades RDF mitjançant negociació de contingut HTTP
N’extreu la informació clau: analitza l’RDF per extreure’n el nom preferit, la data de naixement i la data de mort
Genera el marcatge TEI: crea dos fragments XML essencials:
- Una entrada de fitxer d’autoritats (element <person> amb un xml:id generat, <persName>, <birth>, <death> i <idno type="VIAF">)
- Una etiqueta d’anotació a part (<persName> amb un atribut ref que apunta a l’entrada d’autoritat)

Aquesta doble sortida permet als editors mantenir un fitxer d’autoritats centralitzat i, alhora, inserir fàcilment etiquetes d’anotació en els seus textos TEI.

Característiques principals

Generació d’identificadors normalitzats: crea identificadors XML coherents amb el format pers-[familyname]-[givenname initial] (p. ex., pers-deteligny-c)
Anàlisi d’RDF: fa servir rdflib per extreure informació de diverses propietats RDF (p. ex., rdfs:label, schema:name, viaf:mainHead)
Interfície de línia d’ordres: s’executa amb un número VIAF com a únic argument obligatori
Sortida detallada: proporciona informació detallada del processament juntament amb l’XML final

Exemple d’ús

python persNamer.py 314802260

Aquesta ordre produeix:

<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>

Aplicacions en humanitats digitals

persNamer és especialment útil per a:

Edicions acadèmiques digitals que requereixen control d’autoritats
Projectes de codificació TEI que treballen amb personatges històrics
Iniciatives de dades enllaçades que connecten documents amb registres d’autoritat
Garantir la coherència en grans corpus TEI
Ensenyar els conceptes del control d’autoritats en cursos d’humanitats digitals

Implementació

persNamer està escrit en Python i depèn de:

requests per a les peticions HTTP
rdflib per a l’anàlisi d’RDF
lxml per a la gestió de l’XML

El codi font i la documentació són al .