Sidecar-Integration

Ein Verweis wird Teil eines Dossiers, mit Beleg

Worum es geht

Ein Lebenslauf, den eine Person selbst geschrieben hat, liegt als Seite im Nachlass (http://127.0.0.1:5725/?doc=1-2_ackeret_jacob_1935_1958&p=2: Jakob Ackeret, geboren 17. März 1898, Diplom ETH 1920, Assistent bei Stodola, Göttingen bei Prandtl, Habilitation 1928, o. Prof. seit 1934, ausgewählte Arbeiten nach Gebieten). Was so eine Quelle über die Person sagt, gehört in ihr Dossier, und zwar so, dass jede Aussage nachweist, auf welcher Seite, in welchem Absatz und mit welchem Wortlaut sie steht, wer dafür bürgt und wer sie bestätigt hat. Dann kann jede spätere Begründung, die eine Person betrifft, auf diese Evidenz zeigen.

Die Integration ist eine Funktion mit vier Stufen, als Partitur famulus-integration registriert, und so geschrieben, dass sie für andere Sidecars (Chronologie, Terminologie, LWgrammar-Regeln) dieselbe ist: was sich je Sidecar unterscheidet, steht in einer Karte (integration/karten/<sidecar>.yaml), nicht im Code.

flowchart LR
  V[Verweis: URL, doc:page, Satz-ID, Phrase] --> K[kontext]
  K --> U[untersuchung: DTD-Auszeichnung]
  U --> I[identitaet: Register, Bestand]
  I --> G[integration: Fakten, Prüfungen, Widersprüche]
  G --> D[(Dossier XML + Projektion)]
  D --> E[Explikation · Erkundung · Probe-Labor]
  O[Owner-Verdikt] --> D
  O --> L[(Lernspeicher: Episoden, Diagnosen)]

Die vier Stufen

kontext

Der Verweis wird zur Seite einer Sammlung: der Ordner, der die doc_id hält, wird gesucht, nie geraten. Dazu der Rahmen aus den Registern der Sammlung: die Ordnerzeile (documents), die Briefregistersätze, die die Seiten decken (letters: Art, Datum, Parteien, Regest), die Nachbarn, die Fortsetzung (Seiten desselben Satzes, die nicht übergeben wurden, laufen als fortsetzung mit), die Kandidaten für das Subjekt (Korrespondent des Ordners, Parteien und Personen der Sätze), die Datierung (Datum des Satzes; sonst das späteste genannte Jahr als terminus post quem; sonst die Ordnerjahre) und offene Verweise („s. Beilage“). Jeder Posten nennt Tabelle und Schlüssel. Woher der Rahmen kommt, sagt die Schemakarte der Sammlung (siehe Je Sammlung).

untersuchung

Das Dokument wird gegen die Dokument-DTD des Sidecars ausgezeichnet, für einen Lebenslauf lebenslauf.dtd: Stationen (Geburt, Ausbildung, Stellung, Erfindung …), Werklisten nach Gebiet, Bemerkungen (Beziehungen, Verweise). Das Modell (gemini-3.8-flash, Instruktion pdai/skills/integration/untersuchung-lebenslauf) schlägt die Auszeichnung als JSON vor; gebaut, DTD-validiert und geprüft wird hier: jedes Element ist an einem Absatz verankert (pidx, p) und zitiert ihn wörtlich, jede Zeit ist EDTF. Was die Prüfung nicht besteht, wird verworfen und genannt; nicht erfasste Absätze stehen als rest. Eine Karte ohne Dokument-DTD für die erklärte Art bricht hier mit nicht_pruefbar ab.

identitaet

Das Subjekt: die vom Owner genannte Person (im Register geprüft), sonst der Korrespondent des Ordners. Jeder Name des Dokuments wird gebunden: zuerst über die Personen, die das Briefregister für diese Seite schon aufgelöst hat (letter_persons der Haupt-DB, ohne sie fq_letter_entities und die im Brieftext gebundenen fq_mentions des Sidecars; gleicher Nachname, verträgliche Initialen), sonst über das Verfahren des Registers (ai_lemma_index.register.binden). Was nicht bindet, bleibt unaufgeloest mit seinen Kandidaten. Keine ID wird erfunden. Dann wird der Bestand geladen: Registerkarte, Briefe des Subjekts in der Sammlung, das Dossier, wie es steht.

integration

Ein Fakt je Station, Werk und Beziehung: eine Aussage, ihr typisierter Inhalt, ihre Zeit, ihr Beleg (P:<doc>#<pidx>/p<n>, die Satz-IDs des Stanza-Korpus in diesem Absatz, die Passage) und ihre Quelle (Art, Zeugnis selbst|fremd|amtlich, Urheber, Seiten, URL des Viewers, Datierung, Instruktionsstempel, offene Verweise). Status vorgeschlagen. Dann die Prüfungen der Karte; jeder Befund ist ein widerspruch mit Status offen, seiner Regel und beiden Adressen. Das Dossier wird gegen dossier.dtd validiert, atomar mit neuer Version geschrieben und nach dossier.duckdb projiziert; der Lauf ist eine Episode des Lernspeichers.

Je Sammlung

Jede Stufe liest die Sammlung über ihre Schemakarte (profil): Träger, Sprachen, Epoche, Fach und Datenbanken. Der Kármán-Nachlass ist ein durchgerechnetes Beispiel, nicht die Voreinstellung.

Sammlung	Rahmen (`kontext`)	Briefe des Subjekts (`bestand`)
Korrespondenz mit Haupt-DB (`karman-nachlass`)	`documents`, `letters`, `letter_persons` … der Haupt-DB	`letters_resolved`
Korrespondenz ohne Haupt-DB (`eulerOO-IVA`)	FQL-Sidecar: `fq_documents`, `fq_letters` (Seiten aus `pidx_from`…`pidx_to` und `fq_letter_pages`), Parteien über `fq_entities`, Personen aus `fq_letter_entities` und `fq_mentions`	`fq_letters`
Dokumentsammlung	das Dokument aus `fq_documents` des Sidecars, sonst aus `biblio.xml`; datiert nach seinem Erscheinungsjahr	entfällt (`nicht_anwendbar`), keine Lücke

Die Fortsetzung eines Briefs ohne Haupt-DB sind die übrigen Seiten desselben Teils (Brieftext oder Übersetzung); die Übersetzung an anderer Stelle des Bandes läuft nicht mit. Ordnerjahre gelten nur für eine Korrespondenz, deren doc_id Jahre trägt: eine vierstellige Zahl für sich, innerhalb der Epoche der Sammlung (± 25 Jahre). Eine Sammlung ohne Karte behält die frühere Lesart.

Der Bestandslauf aus dem Briefregister (famulus-integration bestand-lauf --collection <c>) liest Briefe, Parteien und Sprechakte aus dem FQL-Sidecar. Wen ein Brief nennt, liest er aus der Haupt-DB, wo es eine gibt, sonst aus fq_letter_entities und fq_mentions mit Brief-ID. Jede Angabe behält ihren Brief und, wo das Register sie kennt, ihre Seite (pidx_from, sonst die erste Seite in fq_letter_pages); ein Brief, den das Register ohne Seite führt, bleibt ohne Seite.

Die Prüfungen

Regel	Befund
`innerer_widerspruch`	ein Fakt vor der Geburt oder nach dem Tod; eine vom Modell als unklar markierte Zahl (etwa „No. 101946“)
`bestand_widerspruch`	Geburt oder Tod mit anderem Datum als im Dossier; Stellung oder Abschluss bei derselben Institution mit anderen Jahren
`register_widerspruch`	Briefe des Subjekts vor der Geburt oder nach dem Tod
`rahmen_widerspruch`	das Dokument nennt ein Jahr jenseits der Ordnerjahre (nur wo eine Korrespondenz ihre Ordner nach Jahren benennt)
`verweis_offen`	Beilagen und Folgeseiten, die das Dokument nennt und die Übergabe nicht enthält (als `offen` an der Quelle)

Lebenszyklus und Lernen

Ein Fakt ist vorgeschlagen, bestaetigt, verworfen oder revidiert; eine Korrektur schreibt einen neuen Fakt mit ersetzt. Ein Owner-Verdikt (bestaetigen, verwerfen, korrigieren, widerspruch) steht über dem Modell, wird am Element vermerkt und von keinem Neuaufbau rückgängig gemacht (die Projektion spiegelt die XML, sie entscheidet nichts). Jedes Verdikt ist eine Episode des Lernspeichers (lernen/store.py); ein Verdikt gegen das Modell ist eine Diagnose der Untersuchungsinstruktion, die eine Lektion patchen kann. Gemessen wird eine Lektion durch Replay (famulus-integration replay): die Stufen 2 bis 4 laufen auf den gespeicherten Seiten noch einmal, ohne zu schreiben, und die Fakten werden verglichen, nie zwei Live-Läufe.

Wo das Dossier gelesen wird

Das Evidenzpaket der Explikation (Packs.dossier) führt die Fakten mit table: dossier und dem Schlüssel <ind_id>/<fakt_id>; die Instruktion explicate (v1.2) zitiert einen Fakt nur mit diesem Schlüssel und nennt einen vorgeschlagenen als vorgeschlagen.
Die Erkundung (satzrecord/ausdruck/erkundung.py) hat die Quelle dossier: ein stützender Treffer ist ein tragender Grund der Art beleg mit der Seite, auf der der Fakt steht.
Das Probe-Labor (scripts/satz_viewer.py, /api/dossier) und der Kármán-Viewer (/api/dossier/{ind_id}, Knopf „Ins Dossier“) zeigen Fakten, Status und Widersprüche mit Sprung auf die Seite.

Wo die Dossiers zu sehen sind

In der Kármán-Edition öffnet der Knopf „Dossier“ über jeder Seite das Dossier der Person, zu der die Seite gehört (der Korrespondent des Ordners); eine Zahl am Knopf sagt, wie viele Vorschläge noch auf Prüfung warten. Das Dossier erscheint als knappe Biographie: Lebenslauf als Zeitleiste, Erfindungen und Konstruktionen, Werke nach Gebiet, Beziehungen, Quellen und offene Punkte. Ein Klick auf eine Angabe zeigt die wörtliche Belegstelle mit Ordner, Seite und Absatz und die redaktionellen Schritte:

Knopf	Wirkung
Übernehmen	der Vorschlag wird Teil des Dossiers (Status `bestaetigt`)
Keine Änderung	das Dossier bleibt, wie es ist; der Vorschlag steht unter „Nicht übernommen“ und kann dort doch übernommen werden
Ändern …	Aussage oder Zeit (EDTF) berichtigen und so übernehmen; die alte Fassung bleibt als ersetzt in der Geschichte, die Belegstelle bleibt
Kommentar …	eine Bemerkung (stimmt nicht, fehlt etwas, sonstiges) mit Namen; ändert keinen Status, wird als „erledigt“ abgeschlossen

Nach jedem Schritt bleibt das Panel an derselben Stelle und die bearbeitete Zeile offen. Über dem Dossier steht, ob die gezeigte Seite schon Quelle ist („neu lesen“) oder aufgenommen werden kann („Diese Seite aufnehmen“, „Mit dieser Seite anlegen“); während des Lesens zeigt der Balken die vier Stufen. Hat die Person noch kein Dossier, sagt das Panel genau das.

Für das Lernen gilt: „Keine Änderung“ und „Ändern“ sind Diagnosen gegen die Auszeichnungsinstruktion (das Modell hat die Quelle falsch oder ungenau gelesen); wird ein nicht übernommener Vorschlag später doch übernommen, ist die frühere Episode widerrufen. Das Erledigen eines offenen Punkts (etwa einer als unklar markierten Zahl) ist keine Fehlerdiagnose: die Markierung war berechtigt.

Die Aufnahme läuft als Auftrag in famulus-proofs eigenem Interpreter, nicht im Prozess des Viewers: dort ist das Gemini-SDK geladen, und ai_lemma_index.llm verweigert in einem solchen Prozess den Dienst; die Registerbindung brach deshalb ab. Eine Seite, die schon Quelle ist, wird nicht ein zweites Mal gelesen; „neu lesen“ ersetzt nur die offenen Vorschläge dieser Seite, Bestätigtes bleibt.

Kommentare. Ein Kommentar steht beim Fakt (<anmerkung> in dossier.dtd, Art einspruch, ergaenzung oder hinweis) und ist eine Episode des Lernspeichers. Ein Kommentar zum Dossier als Ganzem („etwas fehlt“) steht unter den offenen Punkten.

Alle Dossiers: http://127.0.0.1:5725/dossiers (Link „Dossiers“ in der Kopfleiste), dieselbe Darstellung mit der Liste aller Dossiers jeder Sammlung. famulus-integration dossiers gibt die Übersicht, anmerken und erledigen dasselbe auf der Kommandozeile.

Normdaten und autorisierte Webquellen

Ein Dossier darf sich außer auf Seiten der Edition auch auf Webquellen stützen, aber nur auf solche, die in der Liste autorisierter Webquellen stehen (<collections_root>/_famulus/webquellen.yaml, Modul integration/webquellen.py). Jede Quelle trägt Status (autorisiert, vorgeschlagen, abgelehnt), Zweck (Personen, Orte, Firmen und Institutionen, alle), wahlweise die Register-IDs, für die sie allein gilt, und ein Linkmuster für Kennungen. Eine vorgeschlagene Quelle liest kein Lauf; autorisieren kann nur der Owner, und wer wann autorisiert hat, steht in der Liste. Eine geänderte Adresse verliert die Autorisierung. Die Liste ist auf der Dossier-Seite unter „Webquellen“ bearbeitbar (dossiers?webquellen=1) und über …/api/famulus/webquellen in jedem Viewer erreichbar.

Autorisiert auf Anweisung des Owners vom 19.10.2026 sind die Normdaten-Institutionen mit eigenem Server: Wikidata (abgefragt), GND, VIAF, Library of Congress, GeoNames und Deutsche Biographie (als Kennungen mit aktivem Link, über Wikidata gefunden). Die Seite der NATO STO zur Geschichte von AGARD steht als vorgeschlagen für die sechs AGARD-Einträge des Registers und wartet auf die Autorisierung.

Normdaten-Lauf. famulus-integration normdaten-lauf --collection <c> ordnet jedem Einzelding der Sammlung (Personen, Orte, Firmen und Institutionen) höchstens einen Wikidata-Datensatz zu und trägt dessen Angaben als Vorschläge ein: Quelle typ="web", autoritaet="wikidata", Kennung und Abrufdatum; jede Angabe hat einen Beleg mit aktivem Link auf die Aussage (https://www.wikidata.org/wiki/<Q>#<P>). Die Kennungen (Wikidata, GND, VIAF, LoC, GeoNames, Deutsche Biographie) stehen als Links im Kopf des Dossiers. Der Lauf ist wiederaufnehmbar (<c>/dossier/normdaten-lauf.duckdb) und prüft jede neue Angabe gegen das Dossier, etwa ein Geburtsdatum gegen den Lebenslauf.

Die Zuordnung folgt festen Regeln ohne Sprachmodell. Sie vermeidet falsche Zuordnungen auch um den Preis fehlender: Ein mehrdeutiger Fall wird mit seinen Kandidaten vermerkt, nie geraten.

Art	Eine Zuordnung gilt nur, wenn …
Person	der Datensatz ein Mensch ist; der erste Vorname vorn und der Nachname am Ende des Namens steht; ein Zwischenname des Registers wiederkehrt; die Person beim ersten Beleg volljährig war und als Korrespondent beim ersten Brief lebte; eine nur erwähnte Person, die über 100 Jahre vor dem ersten Beleg geboren ist, einen Fachbezug hat (ein Korrespondent mit diesem Abstand wird nie zugeordnet); bei einem häufigen Namen ein Zwischenname und ein Fachbezug (Beruf) vorliegen
Ort	die Bezeichnung gleich ist; eine genannte Region (auch als Kürzel wie CA, N.J., D.C.) in Beschreibung oder Verwaltungseinheit steht; ein bloßer Ortsname keinen zweiten Ort gleichen Hauptnamens hat
Firma, Institution	die Hauptbezeichnung (bis auf die Rechtsform) gleich ist, ein bloßer Alias genügt nicht; der Datensatz eine einzelne Organisation ist, keine Klasse, kein Gebäude, Werk oder Ereignis; die Gründung nicht nach dem letzten Beleg liegt; Wikidata den Namen nicht als Begriffsklärung führt; kein höher eingestufter Datensatz mit dem Namen beginnt („Washington University in St. Louis“); ein gleichnamiger Datensatz nur hinter einem erheblich bekannteren ersten Treffer zurücktritt (Zahl der Wikipedia-Artikel); ein kaum belegter Datensatz ein Gründungs- oder Auflösungsdatum hat; ein Gattungsname („Department of Transport“) nur auf den ersten, gut belegten Treffer führt

Personen nur mit Initialen, Kürzel und Rufzeichen sowie Gattungsnamen („Ordnance School“) werden mit Grund übersprungen. Der Fachbezug ist die Liste der Berufe (Wikidata P106) im profil.fach der Schemakarte, je Sammlung: ein Theologe hat ihn für pirckheimer und eulerOO, nicht für den Kármán-Nachlass. Der erste Beleg ist das erste Jahr des Einzeldings im Register; kennt das Register keines, gilt für die Hundertjahresregel der Beginn der Epoche der Sammlung (profil.epoche.von). Die Regeln wurden an drei Stichproben der Kármán-Sammlung von Hand gegen Wikidata geprüft; jede gefundene Fehlzuordnung ist ein Testfall in tests/test_normdaten.py.

Erster Lauf (karman-nachlass, 19.10.2026). 18 308 Einzeldinge, 2 105 Dossiers mit Wikidata-Quelle, 12 274 Vorschläge mit Link, alle Dossiers DTD-gültig:

Art	zugeordnet	mehrdeutig	kein Treffer	übersprungen
Personen	829	741	2 926	6 737
Orte	641	956	1 275	—
Firmen und Institutionen	635	414	2 861	293

Übersprungen wird vor allem, wo das Register nur Nachname oder Initialen kennt. Regeln, die während des Laufs geschärft wurden, wendet famulus-integration normdaten-nachpruefen --vor <Zeitpunkt> auf die früheren Zuordnungen an: was nicht mehr folgt, wird zurückgezogen, außer der Owner hat schon darüber entschieden (dann ein offener Punkt). Bericht: runs/integration/normdaten-karman-nachlass-2026-10-19.zusammenfassung.json.

Webseiten. famulus-integration aufnehmen-web --url <adresse> --person <ind_id> liest eine Seite nur, wenn ihre Adresse unter einer für dieses Einzelding autorisierten Quelle liegt; sonst bricht der Aufruf vor jeder Anfrage mit dem Grund ab, und eine Weigerung des Servers (HTTP 403) wird gemeldet. Die Seite wird in nummerierte Absätze zerlegt und durchläuft dieselben vier Stufen wie eine Seite der Edition; jeder Beleg verlinkt seinen Absatz als Text-Fragment (#:~:text=…), sodass der Link die Seite mit markierter Stelle öffnet.

Verweise: weiterführendes Material, kein Beleg

Ein Dossier kann auf weiteres Material zeigen, etwa ein Video oder eine Webseite, ohne dass sich ein Fakt darauf stützt. Dafür hat die DTD den optionalen Block <verweise> am Ende des Dossiers: jeder <verweis> hat Art (video, webseite, bild, dokument, sonstige), Adresse, Titel, Herausgeber, wer ihn wann erfasst hat und ob die Adresse bei der Erfassung antwortete (abrufbar: ja, nein, unbekannt, mit einem Prüfvermerk geprueft). Ein Verweis ist keine Quelle: Er erscheint nicht unter quellen, kein beleg nennt ihn, und keine Prüfung der Validität liest ihn. Die Projektion hat die Tabelle do_verweis; die Dossier-Ansicht zeigt die Verweise unter „Weiterführend“ mit dem Vermerk „kein Beleg“.

Soll eine Webseite Fakten belegen, gilt der Weg über die autorisierten Webquellen (oben); ein Verweis macht eine Seite dafür nicht tauglich.

uv run famulus-integration verweisen I000331 https://www.sto.nato.int/history/ --art video \
    --collection karman-context --titel "History of the organisation — video page of the NATO STO" \
    --herausgeber "NATO Science and Technology Organization" --abrufbar unbekannt \
    --geprueft "2026-10-19: scripted request answered HTTP 403"

Dieselbe Adresse wird nur einmal geführt; ein zweiter Aufruf ersetzt Titel und Beschreibung. Gibt es in der Sammlung noch kein Dossier, legt der Aufruf es aus der Registerkarte an (nur der Personenblock).

Aufruf

uv run famulus-integration aufnehmen 'http://127.0.0.1:5725/?doc=1-2_ackeret_jacob_1935_1958&p=2' \
    --sidecar dossier --person P002043 --art lebenslauf --zeugnis selbst [--dry]
uv run famulus-integration zeigen dossier P002043
uv run famulus-integration bestaetigen P002043 f001
uv run famulus-integration pruefen P002043
uv run famulus-integration normdaten-lauf --collection karman-nachlass [--limit 50] [--bericht runs/integration/….json]
uv run famulus-integration aufnehmen-web --url https://www.sto.nato.int/history/ --person I000282 --art firmenprofil

Ablage, in der PDAI-Sammlung selbst: <collections_root>/<collection>/dossier/<ind_id>.xml (universelle DTD dossier.dtd, Kopie neben den Daten, sha-verglichen), die ausgezeichnete Quelle unter dossier/quellen/<quelle_id>.xml, die Projektion <collection>_dossier.duckdb neben den anderen DuckDBs der Sammlung (in der Schemakarte als datenbanken.dossier). Der Schlüssel ist die globale Register-ID, deshalb trägt eine Person je Sammlung ein Dossier, und fakten(ind_id) ohne Sammlung liest sie alle zusammen (jeder Fakt nennt seine Sammlung) — so konsultiert eine andere Sammlung dasselbe Dossier. Ein Verdikt geht an die Sammlung, die das Element hält. Andere Sidecars: karten/terminologie.yaml (Bindung über lwgrammar_reference.dictionary.lookup_term, Adapter über submit_senses), karten/chronologie.yaml, karten/lwgrammar.yaml — deklariert; ihre Lücken (Dokument-DTD, Ablage) meldet jeder Lauf, bis sie gefüllt sind.