TEI |

persNamer 1.2: jeden numer VIAF, dziewięć kartotek haseł wzorcowych

Mon, 07 Sep 2026 00:00:00 +0000

był na początku zwykłym udogodnieniem: numer VIAF na wejściu, wpis TEI <person> na wyjściu, do tego znacznik <persName>, którym adnotuje się tekst. Nic ponadto – a i sam wpis był chudy: nazwa, dwie daty, jeden identyfikator. Wydana dziś wersja 1.2 wciąż robi tylko tę jedną rzecz, ale wpis, który zwraca, jest nareszcie wart zachowania.

Co dziś zawiera wpis osobowy

Zacznijmy od nazwy. W klastrze VIAF każda uczestnicząca biblioteka wnosi własną formę nazwy, a stary persNamer brał po prostu pierwszą etykietę, jaka mu się nawinęła. Zapytany o Woltera odpowiadał „فولتير،” – po arabsku, z przecinkiem na końcu – i dorzucał do tego pusty xml:id. Teraz program zlicza formy w całym klastrze i zostawia tę, która wśród rekordów źródłowych powtarza się najczęściej; pozostałe idą za nią jako <persName type="variant">, od najczęstszej. Daty są normalizowane (1572-08-00 zamienia się w 1572-08) i zapisywane dwa razy: jako tekst i w atrybucie @when, bo to właśnie tam zajrzy każde przetwarzanie, które ma cokolwiek do czynienia z datami. Płeć i opisy dochodzą, o ile VIAF je udostępnia.

No i to, na czym zależało mi najbardziej: każdy identyfikator, który VIAF wiąże z daną osobą – przez schema:sameAs albo przez własne identyfikatory źródeł – trafia do osobnego <idno>: BnF, GND, Biblioteka Kongresu, SUDOC, Wikidata, ISNI, BNE, LIBRIS, NDL. Jeden numer wchodzi, dziewięć katalogów wychodzi. Dla personografii to cała różnica między listą nazwisk a węzłem w sieci danych wzorcowych.

<person xml:id="pers-teligny-c">
 <persName>Charles de Téligny</persName>
 <birth when="1535">1535</birth>
 <death when="1572-08-24">1572-08-24</death>
 <sex value="M">M</sex>
 <idno type="VIAF">314802260</idno>
 <idno type="BNF">16133360</idno>
 <idno type="Wikidata">Q1868249</idno>
 <idno type="ISNI">0000000071126808</idno>
</person>

Od luźnych fragmentów do personografii

Dla jednej osoby XML wypisany w terminalu w zupełności wystarczy. Edycja ma jednak osób setki. Dlatego persNamer przyjmuje teraz kilka numerów VIAF naraz, grzecznie daje VIAF-owi odetchnąć między jednym żądaniem a drugim, buforuje to, co już pobrał, a z opcją --merge wstawia nowe wpisy prosto do <listPerson> istniejącego pliku TEI. Kogo już tam zapisano, tego rozpoznaje po numerze VIAF i zostawia mu dotychczasowy xml:id; nowe identyfikatory sprawdza względem pliku i w razie kolizji dokleja im przyrostek (-2, -3); na koniec plik dostaje nowe wcięcia – ale dopiero wtedy, gdy kopia .bak leży już odłożona na bok.

persnamer --merge edition.xml 314802260 36925746

Jedna zmiana, o której trzeba wiedzieć: partykuła nazwiska domyślnie wypada już z identyfikatora, toteż Charles de Téligny to odtąd pers-teligny-c, nie pers-deteligny-c. Jeśli twój projekt zdążył się przyzwyczaić do dawnej formy, --keep-particle ją przywraca; jeśli zaś wolisz w ogóle nie polegać na nazwiskach, --id-format viaf da ci pers-viaf-314802260.

Porządki

Ze skryptu zrobił się porządny pakiet z poleceniem persnamer: jedna linijka wystarczy, by go zainstalować (uv tool install albo pipx) lub uruchomić jednorazowo przez uvx, niczego nie instalując. Dwadzieścia sześć testów sprawdza go na nagranych odpowiedziach VIAF – zestaw obywa się więc bez sieci. CI przepuszcza je na Pythonie od 3.9 do 3.13, a wynik jest walidowany względem TEI P5. Licencja: Apache 2.0, jak dotąd.

Czego nadal nie umie, to powiedzieć, gdzie ktoś się urodził ani z czego żył: klastrowy RDF VIAF-u nie zawiera ani miejsc, ani zawodów. Zawierają je za to powiązane rekordy BnF i GND – a ich numery masz już w ręku.

Kod i dokumentacja na .

tei-mcp v0.3: kodowanie TEI bez przepisywania źródła

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

Kiedy , celem było powstrzymanie asystentów AI przed halucynowaniem znakowania TEI. Osadzenie w schemacie rozwiązało część problemu: mając bezpośredni, oparty na narzędziach dostęp do specyfikacji P5, model nie musi już zgadywać, co znaczy dany element ani jakie atrybuty przyjmuje. Wynik przechodzi walidację.

Ale halucynacja w kodowaniu TEI ma dwa oblicza, a schemat wyłapuje tylko jedno z nich. Walidacja względem specyfikacji mówi, że znakowanie jest poprawne. Nie mówi nic o tekście, który to znakowanie obejmuje. A właśnie tam – w samym tekście – gnieżdżą się groźniejsze halucynacje. Kompozycja z blokadą zakresów (span-locked composition), główna nowość w v0.3, została zaprojektowana właśnie po to, by im zapobiegać.

Spis treści

Halucynacja, której schemat nie wyłapie

Poproś model o zakodowanie szesnastowiecznego francuskiego listu, a często dostaniesz z powrotem dokument TEI, który wygląda nienagannie. Nagłówek wypełniony, znaczniki <persName> na swoich miejscach, <dateline> poprawnie zbudowany. Przepuść go przez validate_document – przejdzie.

Potem porównaj tekst główny ze źródłem.

mesme stało się même. Przecinek się przesunął. luy po cichu zmodernizowano na lui. Zdanie trudne do odczytania w rękopisie zostało „poprawione” na coś gładszego. Żadnej z tych zmian nikt nie zlecił. Żadna nie została oznaczona. Dokument jest zgodny ze schematem i po cichu błędny.

W pracy archiwalnej – gdzie zakodowany tekst staje się trwałym zapisem, na którym polegają czytelnicy, indeksy wyszukiwania i cytowania – to właśnie ten rodzaj awarii liczy się najbardziej. Zniekształcony znacznik irytuje. Zmodernizowana pisownia, której nikt nie zauważy przez pięć lat, to skażenie tekstu.

Kompozycja z blokadą zakresów

Nowe wydanie (v0.3) zawiera mechanizm zapobiegania halucynacjom wycelowany dokładnie w ten rodzaj awarii. Cel projektowy: sprawić, by halucynacje w tekście głównym były niemożliwe z samej konstrukcji, a nie tylko mało prawdopodobne.

Pomysł jest prosty: model nigdy nie wpisuje tekstu głównego.

Zamiast tego przebieg pracy wygląda tak:

Model wywołuje get_source("letter_001") i otrzymuje źródłowy czysty tekst jako niezmienny ciąg znaków.
Dla każdego znacznika, który chce zastosować, wywołuje tag_span("letter_001", start, end, element_path, attrs) – rejestrując element TEI na zakresie znaków w źródle.
Gdy skończy, wywołuje compose("letter_001"). Serwer przeplata zarejestrowane znaczniki z pierwotnym czystym tekstem, renderuje końcowy dokument TEI, a następnie sprawdza bajt po bajcie, czy płaska zawartość tekstowa wyrenderowanego dokumentu jest równa źródłu.

Jeśli bajty się zgadzają, dokument wraca. Jeśli nie – jeśli znaczniki modelu w jakiś sposób implikują tekst główny różniący się od źródła choćby jednym znakiem – compose() zgłasza wyjątek, zamiast zwracać skażony dokument.

W tym przebiegu nie ma ścieżki, na której model wyprodukowałby dokument TEI z tekstem głównym różnym od źródła. Ten niezmiennik jest mechaniczny, nie behawioralny. Nie musisz ufać, że model nie halucynuje; musisz ufać porównaniu == dwóch ciągów bajtów.

Czym to jest, a czym nie jest

Kompozycja z blokadą zakresów jest uzupełnieniem osadzenia w schemacie, nie jego zamiennikiem. Narzędzia osadzające w schemacie (validate_document, lookup_element, valid_children i reszta pierwotnej szesnastki) pomagają modelowi wytwarzać poprawne TEI. Kompozycja z blokadą zakresów gwarantuje, że tekst główny wewnątrz tego TEI jest wierny źródłu. Przebieg kodowania nadający się do wdrożenia musi spełniać oba warunki – i teraz oba pokrywa jeden serwer.

Nie jest to też magiczne lekarstwo na wszystko. compose() nie sprawdza jeszcze, czy zarejestrowane znaczniki są dopuszczalne wedle wczytanego dostosowania ODD – to zadanie na później. Zarejestrowane znaczniki żyją w pamięci procesu i nie przetrwają restartu. A pliki źródłowe muszą być czytelne z miejsca, w którym działa serwer. Wszystko to da się rozwiązać; nic z tego nie podważa głównego niezmiennika.

Dlaczego to ważne poza TEI

Ten wzorzec się uogólnia. Zawsze, gdy model ma adnotować, przekształcać lub obudowywać fragment tekstu – i zawsze, gdy integralność tekstu bazowego liczy się bardziej niż zdolność modelu do jego „ulepszania” – stosuje się ten sam kształt rozwiązania. Nie każ modelowi przepisywać tekstu. Każ mu wytwarzać instrukcje nad tekstem, a deterministycznemu kompozytorowi pozwól je zastosować pod niezmiennikiem równości.

Dla edycji cyfrowych w szczególności zmienia to zakres tego, co można odpowiedzialnie zlecić modelowi. Kodowanie staje się nagle zadaniem, które można delegować bez ręcznego porównywania każdego wyniku ze źródłem. Maszyna idzie nudną ścieżką; edytor sprawdza znakowanie, nie pisownię.

Jak pobrać aktualizację

Jeśli masz już zainstalowany tei-mcp:

uvx tei-mcp@latest

Albo od zera:

pip install tei-mcp

Aby korzystać z kompozycji z blokadą zakresów, wskaż serwerowi katalog z plikami źródłowymi w postaci czystego tekstu:

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

Rdzeń nazwy każdego pliku staje się identyfikatorem dokumentu (letter_001.txt → letter_001).

Kod źródłowy, pełna dokumentacja i notatki projektowe dotyczące niezmiennika:

tei-mcp

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

tei-mcp: TEI P5 dla agentów AI

tei-mcp to serwer open source, który daje asystentom AI do kodowania bezpośredni dostęp do specyfikacji . Zamiast polegać na zapamiętanych danych treningowych – co często daje znakowanie wiarygodne z pozoru, lecz błędne – AI może odpytywać specyfikację w czasie rzeczywistym.

Funkcje

Serwer parsuje ODD TEI P5 i udostępnia 16 narzędzi:

Wyszukiwanie dowolnego elementu, klasy, makra lub modułu po nazwie, bez rozróżniania wielkości liter i z podpowiedziami przy literówkach
Rozwiązywanie atrybutów w całej hierarchii klas TEI (lokalne + dziedziczone)
Rozwijanie modeli zawartości w ustrukturyzowane drzewa, z rozwiązywaniem klas i makr
Sprawdzanie zagnieżdżeń – bezpośrednia relacja rodzic–dziecko lub rekurencyjna osiągalność ze śledzeniem ścieżki
Walidacja dokumentów względem TEI P5: modele zawartości, atrybuty, zamknięte listy wartości, spójność odwołań i ostrzeżenia o elementach przestarzałych
Walidacja pojedynczych elementów na potrzeby przyrostowej edycji
Wczytywanie dostosowań ODD, by zawęzić schemat do podzbioru właściwego dla projektu
Przeszukiwanie wszystkich typów encji wyrażeniami regularnymi

Instalacja

pip install tei-mcp

Albo uruchom bezpośrednio:

uvx tei-mcp

Użycie

Dodaj do dowolnego klienta zgodnego z MCP (Claude, Cursor, Windsurf itd.):

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

Kod źródłowy i dokumentację znajdziesz w .

tei-mcp: TEI P5 dla agentów AI

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

Kto choć raz prosił asystenta AI o napisanie TEI XML, ten zapewne zauważył, że coś mu nie wychodzi. Elementy pojawiają się tam, gdzie nie powinny. Atrybuty są zmyślone. Reguły zagnieżdżania – ignorowane. Model ma z grubsza pojęcie, jak wygląda TEI, ale żadnej pewnej wiedzy o specyfikacji.

tei-mcp rozwiązuje ten problem, dając agentom AI bezpośredni, oparty na narzędziach dostęp do wytycznych TEI P5.

Spis treści

Czym jest MCP?

(MCP) to otwarty standard, który pozwala aplikacjom AI łączyć się z zewnętrznymi źródłami danych i narzędziami. Można o nim myśleć jak o porcie USB dla AI: jeden protokół, dzięki któremu każdy zgodny klient – Claude, Cursor, Windsurf i inne – może się podłączyć do wyspecjalizowanych usług.

Serwer MCP udostępnia narzędzia, które AI może wywoływać w trakcie rozmowy. Zamiast polegać na zapamiętanych danych treningowych, model może odpytać żywe, miarodajne źródło.

Co robi tei-mcp

tei-mcp parsuje specyfikację ODD TEI P5 i udostępnia 16 narzędzi, które odpowiadają na najczęstsze pytania edytora czy kodera:

Co to za element? Wyszukaj dowolny element, klasę, makro lub moduł po nazwie, bez rozróżniania wielkości liter i z podpowiedziami przy literówkach.
Jakie przyjmuje atrybuty? Rozwiąż atrybuty w całej hierarchii klas – najpierw lokalne, potem po kolei dziedziczone.
Co może się w nim znaleźć? Rozwiń modele zawartości w ustrukturyzowane drzewa albo pobierz płaską listę dopuszczalnych dzieci.
Czy ten element może tu stać? Sprawdź zagnieżdżenie rodzic–dziecko albo prześledź osiągalność w całej hierarchii elementów.
Czy mój dokument jest poprawny? Zwaliduj plik TEI XML względem specyfikacji: modele zawartości, wartości atrybutów, zamknięte listy wartości, spójność odwołań i ostrzeżenia o elementach przestarzałych.
A co z moim schematem projektowym? Wczytaj plik dostosowania ODD, by zawęzić wszystko powyższe do podzbioru TEI właściwego dla twojego projektu.

Dlaczego to ważne

Kodowanie w TEI wymaga ciągłego zaglądania do wytycznych. Doświadczeni koderzy mają najczęstsze wzorce w małym palcu, ale nawet oni muszą sprawdzać w specyfikacji mniej znane elementy czy złożone modele zawartości. Dla asystentów AI, które takiej przyswojonej wiedzy nie mają, problem jest poważniejszy: halucynują znakowanie, które wygląda wiarygodnie, ale jest błędne.

Z tei-mcp AI nie musi zgadywać. Może sprawdzić odpowiedź w specyfikacji, zanim napisze choćby jeden nawias ostry. W rezultacie powstaje znakowanie zgodne z TEI P5 – albo z dostosowaniem ODD twojego projektu.

Pierwsze kroki

Zainstaluj z PyPI:

pip install tei-mcp

Następnie dodaj go do konfiguracji swojego klienta MCP:

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

Serwer pobiera specyfikację TEI przy pierwszym uruchomieniu i współpracuje z każdym klientem zgodnym z MCP.

Kod źródłowy i pełna dokumentacja:

Multi-Saxon

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

Multi-Saxon: równoległe przetwarzanie XSLT dla dużych korpusów TEI

Multi-Saxon wypełnia istotną lukę w narzędziach do przetwarzania XML: umożliwia równoległe wykonywanie transformacji XSLT 2.0 i 3.0, z którymi LXML (popularna pythonowa biblioteka XML) sobie nie radzi. Zaprojektowany z myślą o dużych kolekcjach dokumentów XML TEI, Multi-Saxon znacząco skraca czas przetwarzania dzięki sprawnemu wykonywaniu równoległemu.

Główne funkcje

Zaawansowana obsługa XSLT: przetwarza transformacje XSLT 2.0 i 3.0, wykraczające poza możliwości LXML
Przetwarzanie równoległe: radykalnie skraca czas transformacji dużych kolekcji dokumentów dzięki zrównolegleniu
Zoptymalizowany pod TEI: zaprojektowany specjalnie dla dokumentów XML Text Encoding Initiative (TEI)
Skalowalna wydajność: sprawnie obsługuje korpusy liczące od setek do tysięcy dokumentów
Wieloplatformowość: działa w różnych systemach operacyjnych i środowiskach

Problem, który rozwiązuje Multi-Saxon

Badacze humanistyki cyfrowej pracujący z TEI często napotykają dwie poważne trudności:

LXML (powszechnie używana pythonowa biblioteka do przetwarzania XML) obsługuje tylko XSLT 1.0, co uniemożliwia korzystanie z bardziej zaawansowanych funkcji XSLT 2.0/3.0
Sekwencyjne przetwarzanie dużych korpusów dokumentów TEI bywa zaporowo czasochłonne

Multi-Saxon rozwiązuje oba problemy: wykorzystuje zaawansowane możliwości XSLT procesora Saxon i rozdziela przetwarzanie między wiele rdzeni, co daje znaczny zysk wydajności.

Implementacja

Multi-Saxon łączy Pythona z javowym procesorem Saxon, tworząc wydajny potok transformacji:

korzysta z javowej biblioteki Saxon do niezawodnego przetwarzania XSLT 2.0/3.0
implementuje wieloprocesowość, by rozdzielić transformacje między dostępne rdzenie CPU
sprawnie zarządza pulami procesów, by zmaksymalizować przepustowość
oferuje prosty interfejs do wsadowego przetwarzania dokumentów TEI

Przykład użycia

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

Znaczenie dla humanistyki cyfrowej

Projektom humanistyki cyfrowej pracującym z dużymi kolekcjami dokumentów TEI Multi-Saxon umożliwia:

złożone transformacje całych korpusów, niewykonalne w LXML
radykalnie krótszy czas przetwarzania (często 5–10-krotnie na systemach wielordzeniowych)
bardziej wyrafinowaną analizę dzięki zaawansowanym funkcjom XSLT 2.0/3.0
prostszy przepływ pracy przy przetwarzaniu całych kolekcji dokumentów

Kod źródłowy i dokumentację znajdziesz w .

persNamer

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

persNamer: łącznik między TEI a Virtual International Authority File

persNamer to wyspecjalizowane narzędzie w Pythonie, które usprawnia włączanie wzorcowych danych osobowych z VIAF (Virtual International Authority File) do dokumentów TEI XML. Zamieniając identyfikatory VIAF w gotowe do użycia znakowanie TEI, persNamer znacząco ogranicza ręczną pracę przy tworzeniu ustrukturyzowanych wpisów osobowych w cyfrowych edycjach naukowych.

Kontrola haseł wzorcowych w TEI – w czym trudność

Cyfrowe edycje naukowe często wymagają precyzyjnej identyfikacji postaci historycznych, wraz z ich znormalizowanymi nazwami i datami życia. Utrzymanie spójnej kontroli haseł wzorcowych w całym projekcie wymaga:

zidentyfikowania osób w tekstach historycznych
odnalezienia miarodajnych danych na ich temat
utworzenia poprawnie sformatowanych wpisów TEI
zapewnienia spójnych odwołań w całym projekcie

Kroki te wykonuje się zazwyczaj ręcznie; są czasochłonne i podatne na niespójności.

Jak działa persNamer

persNamer automatyzuje ten przepływ pracy:

Pobiera dane z VIAF: dla podanego identyfikatora VIAF narzędzie pobiera dane RDF, korzystając z negocjacji treści HTTP
Wydobywa kluczowe informacje: parsuje RDF, by wyodrębnić preferowaną formę nazwy, datę urodzenia i datę śmierci
Generuje znakowanie TEI: tworzy dwa niezbędne fragmenty XML:
- wpis do kartoteki haseł wzorcowych (element <person> z wygenerowanym xml:id, <persName>, <birth>, <death> oraz <idno type="VIAF">)
- osobny znacznik adnotacji (<persName> z atrybutem ref wskazującym na wpis wzorcowy)

Ten podwójny wynik pozwala edytorom utrzymywać scentralizowaną kartotekę haseł wzorcowych, a zarazem bez trudu wstawiać znaczniki adnotacji do tekstów TEI.

Główne funkcje

Znormalizowane generowanie identyfikatorów: tworzy spójne identyfikatory XML w formacie pers-[familyname]-[givenname initial] (np. pers-deteligny-c)
Parsowanie RDF: używa rdflib, by wydobywać informacje z różnych właściwości RDF (np. rdfs:label, schema:name, viaf:mainHead)
Interfejs wiersza poleceń: proste uruchomienie z numerem VIAF jako jedynym wymaganym argumentem
Tryb szczegółowy: wyświetla szczegółowe informacje o przetwarzaniu obok końcowego wyniku XML

Przykład użycia

python persNamer.py 314802260

Polecenie to zwraca:

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

Zastosowania w humanistyce cyfrowej

persNamer przydaje się szczególnie w:

cyfrowych edycjach naukowych wymagających kontroli haseł wzorcowych
projektach kodowania TEI dotyczących postaci historycznych
inicjatywach danych powiązanych, łączących dokumenty z rekordami wzorcowymi
zapewnianiu spójności w dużych korpusach TEI
nauczaniu kontroli haseł wzorcowych na kursach humanistyki cyfrowej

Implementacja

persNamer napisano w Pythonie; zależy od bibliotek:

requests do żądań HTTP
rdflib do parsowania RDF
lxml do obsługi XML

Kod źródłowy i dokumentację znajdziesz w .