An agentic edition pipeline for the court records of Sigismund of Tyrol (1427–1496), held by the Tyrolean State Archives.
Public site, German working guide and project knowledge.
For a first local start, follow the compact German guide. Create a GitHub account if needed, clone with GitHub Desktop and use Python in the VS Code terminal. The guide covers setup, starting, editing and saving. Detailed Git and recovery instructions remain below.
DoCTA supports source-based research into court practices, possession and object movement, and the use of space. The research conversation starts with the historical question, then the material, the information to annotate and its intended analysis. The project plan connects those decisions to a bounded editorial pilot.
The local working edition displays facsimile and transcription together. It saves line corrections with their previous reading, reviewer and timestamp, and lets the editor build a person index and controlled vocabulary through source-bound assignments. It has no time tracking or page approval controls. Saved corrections are distinct from scholarly acceptance of a complete source. Current results and remaining work identify the evidence for each implemented part.
Account books (Raitbücher), castle and personal inventories, copybooks and court ordinances form the source programme. Account books are the leading research source. Inventories currently supply the working-editor demonstration. The account-book edition still requires accepted reference text and research annotations.
The working edition is version 0.2.0. It is an internal research version. Public availability and scholarly acceptance are separate from this software version.
Clone the repository with GitHub Desktop, following the guide. The project copy contains start-editor.cmd, start-editor.command and pipeline/local_editor.py together with Git history. Use this same working folder for subsequent sessions and receive updates through Fetch and Pull after saving, committing and backing up local work. Obtain the agreed working version before starting, since the public website and the local editor can be at different revisions.
Install Python 3.14. On Windows, install the Python Install Manager from the Microsoft Store, published by the Python Software Foundation, and run py install 3.14. On macOS, use the installer from python.org. Open the cloned folder in VS Code and choose Terminal, New Terminal. Create a project environment and install the runtime packages once:
Windows:
py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r editor-requirements.txtmacOS:
python3.14 -m venv .venv
./.venv/bin/python -m pip install -r editor-requirements.txtStart each session with .\.venv\Scripts\python.exe pipeline/local_editor.py --open-browser on Windows or ./.venv/bin/python pipeline/local_editor.py --open-browser on macOS. Keep the terminal open while editing. No environment activation or PowerShell execution-policy change is needed. Live Server and python -m http.server only serve the static site and do not provide the correction or annotation write API.
For maintainers already using uv, uv run --locked python pipeline/local_editor.py --open-browser remains supported. The existing launchers also retain their uv and prepared-environment paths. editor-requirements.txt is the runtime-only export of uv.lock; regenerate it when dependencies change with uv export --locked --no-dev --no-emit-project --no-hashes --format requirements-txt --output-file editor-requirements.txt. The editor installation uses pip and does not require uv. Do not use pip install . for this flat script repository.
Open the silver inventory used in the joint reading or the Thaur inventory. The local URL addresses your own computer. Source images may require network access. Reading, correcting and annotating existing material requires no LLM API key.
If the port is occupied, the starter leaves the running service intact. Stop your old editor before starting the new version, or use --port 8744 and open the URL printed by the new server. The macOS launcher requires native verification on the recipient computer. The CI configuration covers Windows, macOS and Linux when it runs on the remote repository.
- Open Bearbeiten, enter initials and correct a line against the image.
- Select Änderungen speichern and wait for confirmation. Reload to inspect the saved reading. Enter alone retains a browser draft.
- Select a passage in a saved line and choose Begriff to assign a controlled term, or Person, Ort or Datumsangabe for the corresponding annotation. The annotation field holds the optional note and register assignment.
- Open Index to find saved entries and return to their source occurrences.
- Use Weitere Funktionen to derive and validate edition output from saved work when needed. Saved data, generated output, Git commits and publication are separate steps. Editorial register assignments currently export separately as JSON.
Work on the sources relevant to your research. Annotation requires no artificial text correction. Correct a reading only where the image supports it. Änderungen verwerfen discards the current page draft and preserves saved text. Leave an uncertain reading unchanged and attach a note to the selected passage. Source spelling stays in the transcription even when a register entry uses a normalized name.
Before finishing, save text changes and every open annotation form separately. Stop the server with Ctrl+C in its terminal after saving. For the next session, run the start command again and reopen the local link. Saved corrections and annotations reside in the project folder. Clearing browser storage can remove unsaved drafts.
After saving and stopping the editor, GitHub Desktop shows the changed project files. Select only the intended research changes, enter a short description and commit them to main. Editorial work stays on main. A commit records a local version. A separate folder backup protects against loss of that local copy. Push origin uploads commits and makes their contents and history visible in this public repository, so agree which research data may be published before pushing. Changes under docs/ on main also update GitHub Pages. Text events live under pipeline/reviews/, effective readings under pipeline/pages/, and the editorial register under pipeline/registry/. Retained legacy tags and machine-proposal decisions remain in their existing sidecars. The service saves these files without committing them.
In GitHub Desktop, select the intended files under Changes, write a Summary and choose Commit to main. Keep effective readings and their review events together. Push origin sends agreed commits to GitHub. An invitation alone does not transfer data.
For updates, save and stop the editor, commit local changes and back up the folder. Keep Current Branch set to main, then use Fetch origin and Pull origin if available. If Git reports conflicts, preserve the current work and seek help rather than discarding data. After updating, rerun the environment's python -m pip install -r editor-requirements.txt, start the editor and check a known correction and occurrence. Follow version-specific migration instructions if the data contract changes.
For a full backup, copy the stopped project folder to a separate drive and retain the previous dated backup. Unsaved browser drafts are not included. To restore on the same operating system, keep the old folder, restore the backup separately and verify a known correction and index occurrence. For a new machine or operating system, clone again and arrange transfer of unpushed work. A fresh clone only contains data already uploaded. The recovery contract names the canonical folders and compatibility requirements.
If a save reports a conflict, retain the unsaved wording, reload the current saved state and reconcile the readings before saving again. If the browser cannot connect, inspect the terminal for a startup error and confirm that the editor is still running. Do not discard a draft to resolve an unexplained error.
Feedback should include the document and page, the action attempted, the expected result and the observed result. A screenshot can help identify an interface problem. Use the agreed internal feedback channel while source rights remain unresolved.
- Select text within one saved transcription line. A small toolbar offers Person, Begriff, Ort and Datumsangabe. Right-clicking the selection also opens the toolbar. Auswahl annotieren and Alt+A provide an explicit alternative.
- Choose a category. The same field beside the passage contains the assignment and its history. For persons, places and terms, search for an existing register entry or choose Neuer Registereintrag. Create or edit the entry in that field, save it, then explicitly save the occurrence. Noch nicht zugeordnet retains an unresolved occurrence with a note.
- For a date, retain the source wording and optionally enter a normalized year, month or day using
YYYY,YYYY-MMorYYYY-MM-DD. A Zeitraum can have an earliest and/or latest bound. Unsichere Datierung records uncertainty. The editor decides the historical interpretation and any calendar conversion. Validation uses the proleptic Gregorian calendar, without automatic conversion. - Save the occurrence with your initials. Click its editorial mark to edit or remove it later. Removing an annotation preserves the source text and retains the previous value in history. Closing the inline field retains unsaved input, available through Annotation fortsetzen. Explicit discard removes that draft.
- Open Register to search persons, places and terms in a collapsible sidebar. Entries hold a preferred label, spelling variants and notes. Terms may have a broader term. Fundstellen link back to source passages, and equal names remain independent identities. Register als JSON exportieren downloads the saved entries, occurrences and history.
If source text changes, affected occurrences require checking. Their retained quotations remain inspectable. Select the new wording to create a replacement occurrence, and remove the superseded occurrence when appropriate. The first version anchors selections within a single existing line. It does not split or merge transcription lines.
The editorial register identifies persons and classifies source occurrences. Every identity and vocabulary decision in this register comes from the editor. A person entry contains a preferred label, spelling variants, a note and the history of its source-bound assignments. Assigning the term Polster does not establish that two sources describe the same physical cushion. Verbs can be recorded as editor-controlled terms when the research question requires them. The interface has no dedicated verb category. These explicit assignments remain independent of the automatically generated extraction index. They are saved with their history in pipeline/registry/index.json and exported as JSON. The existing TEI and graph build continues to use machine-proposal curation and does not yet incorporate the new editorial register.
Quellen opens the searchable source overview with all source types and availability states visible by default. Availability filters distinguish sources with transcription, sources with a stored image address and archival records. Image-only sources open the first image whose address is recorded. The viewer names the documented total separately and does not invent missing pages. Transcription attribution is shown on the source row and in the viewer. Research preview links to the project explanation.
The separate Schlagwörter dialog is retired. Earlier tag files and browser drafts remain preserved; new controlled terms are assigned through the common annotation field. Historical tags are not automatically converted into register entries.
Index beside Viewer opens the editor-owned person and place index and controlled vocabulary. Search preferred names, spelling variants and notes, or filter by category. A selected entry shows its description, broader term where recorded, and source occurrences. Follow a Fundstelle to reopen that exact assignment in the viewer. Equal names remain independent entries. The page reads saved entries and does not merge or import the generated machine index.
The annotation field in the viewer contains only editorial assignments. Selecting source text performs no LLM call and displays no automatic proposal. The historical editor builds the index and vocabulary through explicit assignments. Earlier extraction files and annotation decisions remain in the project data, available to their existing processing workflows.
Transcription provenance remains visible independently of editorial annotation. It identifies the recorded transcription LLM and saved human corrections. Details provide the recorded source run and prompt metadata. Missing model information in imported text remains explicitly unknown. The annotation contract defines the implemented scope.
The public GitHub Pages viewer supports browser transcription drafts and JSON export. Writing corrections and register assignments into project files requires the local editor. Source exports and prior transcription runs remain available. The persistence model describes revision checks and output generation.
DoCTA/
├── docs/ Published site, GitHub Pages serves this folder on main
│ ├── *.html index, viewer, exploration, benchmark, about
│ ├── css/, js/, lib/ Design tokens, shared ES6 modules, vendored dependencies
│ ├── data/ Pre-processed JSON read by the site
│ └── knowledge/ The Promptotyping knowledge base, Markdown read in the repository
├── evaluation/
│ ├── benchmark/ Versioned prompt benchmark: page set, prompts, runs, metrics
│ ├── pilot/ The benchmark prompts on continuous, uncurated material
│ ├── pilot2/ The same frozen configuration on a wider slice of unseen material
│ ├── checks/ Reference-free checks over transcription runs, currently the
│ │ arithmetic probe of the account-book amounts
│ └── edition/ The pipeline's own per-page VLM transcriptions for edition use
├── experiments/
│ └── transcription-test/ The frozen first VLM transcription test of 26.08.2026
├── pipeline/ Page register (one entry per page with content class, empty
│ │ evidence, verification status and provenance-tagged runs),
│ │ TEI generation, validation and the cross-artifact healthcheck
│ ├── accounts/ Executable part of the account-book encoding specification
│ ├── reviews/ Saved correction events
│ ├── annotations/ Retained decisions on machine entity proposals
│ ├── tags/ Retained legacy page and line tags
│ ├── registry/ Editor-owned entries, source assignments and history
│ ├── prompts/ Prompts used by the pipeline's extraction scripts
│ └── schema/ Vendored TEI P5 grammar and the project schema docta.rng
├── scripts/ Python build-time scripts for data fetching and transformation
└── tests/ Playwright smoke and interaction tests against the published site
The site is static: vanilla JavaScript with ES6 modules, no build process, dependencies vendored in docs/lib/. Details are in docs/knowledge/architecture.md.
The figures the site shows are computed in the browser from the source catalogue in docs/data/sources.json and the register projection in docs/data/pipeline/register_summary.json, so no count is hard-coded in a page. Benchmark results live in evaluation/benchmark/summary.json, with the published export under docs/data/benchmark/.
The document register lists the knowledge documents and their maintenance roles. Start with the project charter for research scope, the joint walkthrough for the meeting, or the handoff for current evidence and open work.
Pipeline documentation defines stored data and processing commands. Test instructions describe the executable checks. Agents enter through CLAUDE.md.
- SiCProD, the prosopographic database of Sigismund's court, supplying persons, places, court offices and relations through a public API
- Transkribus, collection 2197991, holding the facsimiles and the inventory working transcriptions, with facsimiles served over IIIF
- Inventaria, an edition of castle inventories on Transkribus Sites (FWF project P 35988, led from the University of Salzburg with the University of Innsbruck). DoCTA uses only material Inventaria has published, and cites it with attribution wherever a transcription is displayed or evaluated.
The project is built with Promptotyping. Maintained knowledge guides the versioned implementation through preparation, exploration, distillation and implementation. Formal validation checks the data structures. Scholarly acceptance requires source-based judgement under an agreed convention.
DoCTA is a collaboration between the historical project lead at the University of Salzburg and Digital Humanities Craft OG, which builds the digital component. coOCR/HTR is a sister project on transcription quality assessment and serves as the design and method reference.
Source code is licensed under the MIT License. Research data and the documents in docs/knowledge/ are licensed under CC BY 4.0.
Historical source material is the property of the Tyrolean State Archives. IIIF facsimiles are served by Transkribus (READ-COOP). Published Inventaria transcriptions carry the terms of that project.