Universelle Buch-Ingestion & Sprach-Architektur

Das liberino-ai-System ist darauf ausgelegt, jedes beliebige Buch unabhängig von Genre, Sprache, Verlag oder Illustrationsstil ohne buchspezifische Code-Anpassungen zu analysieren.

1. Modulare Sprach-Mappings (src/config/languages/)

Statt linguistische Heuristiken im Code zu verstreuen, sind alle sprachabhängigen Regeln in typisierten Mapping-Dateien gekapselt:

src/config/languages/
├── types.ts    # LinguisticMapping Interface & UnsupportedLanguageError
├── de.ts       # Deutsches Mapping (Redeverben, Impressum, TOC, Guimet-Quotes »...«)
├── en.ts       # Englisches Mapping (speech verbs, imprint, TOC, Smart-Quotes “...”)
└── index.ts    # Spracherkennung (detectLanguage) & Mapping-Registry

Aufbau des LinguisticMapping

export interface LinguisticMapping {
  languageCode: string;             // ISO-Code (z. B. 'de', 'en')
  languageName: string;             // 'Deutsch', 'English'
  speechVerbs: string[];            // Verben der wörtlichen Rede
  imprintKeywords: string[];        // Impressum & Urheberrecht
  tocKeywords: string[];            // Inhaltsverzeichnis-Marker
  authorBioKeywords: string[];      // Autoren-/Illustratoren-Porträts
  promoKeywords: string[];          // Verlagswerbung & Buchempfehlungen
  promoRegexes: RegExp[];           // Regexes für Trailer-Werbung an Kapitelenden
  quotePairs: Array<[string, string]>; // Anführungszeichen z. B. ['»', '«'], ['“', '”']
}

Vollständige Sprachabdeckung (73 KI-unterstützte Sprachen)

Das System verfügt über verifizierte, typisierte linguistische Mappings für alle 73 Sprachen, die von aktuellen Frontier-KI-Modellen (OpenAI GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro) für Sprachverständnis und -generierung flüssig beherrscht werden:

Jedes dieser Mappings definiert:

• speechVerbs: Kulturell und grammatikalisch authentische Verben der wörtlichen Rede (sagte, erwiderte, whisper, shout, etc.).
• imprintKeywords & tocKeywords: Präzise Filterung von Impressums-, Urheberrechts- und Inhaltsverzeichnisseiten vor der Entitätsextraktion.
• authorBioKeywords & promoKeywords: Vollständige Bereinigung von Autoren-Biografien und Werbeblöcken am Buchende.
• quotePairs: Typografisch korrekte Anführungszeichen (z. B. »...«, „...“, “...”, «...», 「...」).

2. Entkoppelte 2-Phasen Ingestion & Szenen-bewusstes Matching

Visuelle und textuelle Extraktion arbeiten in einer robusten, mehrstufigen Pipeline zusammen:

graph TD
    Book[EPUB Buch-Archiv] --> Lang[Spracherkennung & LinguisticMapping]
    
    subgraph "Phase 1: Globale Text-Extraktion"
        Lang --> TextExtract[LLM Semantic Entity Profiling]
        TextExtract --> LoreProfiles[Kanonische Text-Profile, Attribute & Negative Regeln]
    end
    
    subgraph "Phase 2: Szenen-konditionierte Bild-Analyse"
        Book --> VisualExtract[Saliente Vordergrund-Detektion]
        LoreProfiles -. Dynamische Story-Kandidaten .-> VisualExtract
        VisualExtract --> VisualClusters[Visuelle Entitäts-Cluster & Farbpaletten]
    end
    
    subgraph "Phase 3: Cross-Modales Matching"
        LoreProfiles --> Matcher[CrossModalMatcherService]
        VisualClusters --> Matcher
        Matcher --> Bipartite[Szenen-Kookkurrenz & Ausschluss-Regeln]
        Bipartite --> FinalLore[Zugeordnete Bounding-Boxes & Lore-Avatare]
    end
    
    subgraph "Phase 4: Cross-Illustration Consensus"
        FinalLore --> Consensus[VisualConsensusReconciliationService]
        Consensus --> Verified[Konsistente Buch-Entitäten]
    end

Kernprinzipien der Erkennung & Zuordnung

1. Szenen- und Textstellen-konditionierte Vision-Analyse (extractVisualEntities):

   • Jede Illustration wird zusammen mit ihrem genauen Text-Anker (cueText) sowie den Sätzen der Szene (sceneText, prevSceneSnippet, nextSceneSnippet) an das Vision-Modell übergeben.
   • Entitäten aus Phase 1, die im aktuellen Szenentext vorkommen, werden mittels LoreProfileFormatterService.formatForVisionPrompt strukturiert aufbereitet und als primäre Kandidaten mitgeschickt.
   • Das Vision-Modell generiert:
     • sceneSummary: Detaillierte Textbeschreibung der Illustration und der Interaktionen.
     • visualStyle: Bestimmung des Kunst- und Malstils (z. B. Aquarell mit Tusche-Outlines).
     • detected: Exakte normalisierte Bounding Boxes ([ymin, xmin, ymax, xmax] in 0–1000), visuelle Beschreibungen und Hex-Farbcodes für alle sichtbaren Figuren, Objekte und Schauplätze.

2. Automatisches Zuschneiden (Sharp) & Verknüpfung in Directus:

   • Jede Bounding Box wird verlustfrei als WebP-Teilausschnitt zugeschnitten und in Directus als Datei gespeichert (crop_${name}_${timestamp}.webp).
   • Die Teilausschnitte werden direkt mit lore_entities (avatar_file_id, visual_segments) sowie in den Metadaten der jeweiligen Szene (scenes.illustration_metadata) verknüpft.

3. Szenen-bezogene Einzigartigkeit & Entrauschung:

   • Innerhalb einer einzelnen Illustration kann eine einzigartige Figur nur einmal vorkommen (Deduplizierung).
   • Winzige Bildflecken (< 10 Promille Bildfläche) und generische Hintergrundelemente ohne Text-Erdung werden automatisch gefiltert.

4. Cross-Illustration Consensus (VisualConsensusReconciliationService):

   • Vergleicht die visuellen Fingerabdrücke aller Bounding-Boxes desselben Charakters buchweit.
   • Erkennt echte Ausreißer anhand drastischer Farbabweichungen von der etablierten Konsens-Palette, ohne durch normale Kameraperspektiven (Nahaufnahme vs. Totale) Fehlalarme auszulösen.

5. Kapitel- und Szenen-Isolierung für Objekte (CrossModalMatcherService):

   • Gegenstände und Requisiten werden strikt auf die Kapitel beschränkt, in denen sie laut Text vorkommen (chapterOccurrences).
   • Schließt Lore-Gegenstände aus späteren Kapiteln für frühere Szenen kategorisch aus.
   • Unzugeordnete Hintergrund-Requisiten (z. B. gewöhnliche Stühle, Tische, Tassen, Strandkörbe) werden mit hoher Schwellenwert-Prüfung vor Fehlsynonymen geschützt und nicht als Bounding-Box-Rauschen in den Reader übernommen.

Objektive Buch-Häufigkeitsanalyse (FrequencyTier) & Ontologische Typentrennung

Entitäten werden ontologisch strikt nach Typ getrennt und rein datengetrieben über ihre Szenen- und Kapitel-Kookkurrenz-Matrix klassifiziert. Kategorien werden in der Benutzeroberfläche stets voll ausgeschrieben und einheitlich neutral gestaltet (gleicher Hintergrund, rein informativer Charakter ohne Bevorzugung):

• character: Ausschließlich lebendige, beseelte oder animierte Wesen (Personen, Tiere, Fabelwesen, Figuren).

  • Hauptrolle: Hohe Präsenz (frequent oder >= 10 Szenen)
  • Nebenrolle: Wiederkehrende Präsenz (moderate oder >= 3 Szenen)
  • Statist: Sporadische Einzelerwähnung (rare)

• location: Schauplätze, Landschaften, Städte, Architektur:

  • Schauplatz: Alle Ortschaften und Szenerien

• object: Physische Gegenstände, Requisiten, Werkzeuge, Fahrzeuge:

  • Gegenstand: Handlungsgegenstände und Objekte

• frequent (🔥 Häufig im Buch): Hohe Szenen-Präsenz über das gesamte Buch (>= 5 Szenen oder >= 25% aller Szenen).

• moderate (⚡ Mittlere Häufigkeit): Wiederkehrende Präsenz in 2 bis 4 Szenen.

• rare (🌱 Selten / Einzelfall): Einmalige oder sporadische Erwähnung im Buch.

Negative & kontrastierende Regeln

• Strukturierte Attribute (Primär & Sprachunabhängig): Vorrangig werden symbolisch typisierte Attribute wie ageCategory (child, adult, elder), hasWings (boolean) und relativeScale.scale_category (tiny, small, medium, large, colossal) ausgewertet. Dadurch entfällt fehleranfälliges Regex-/String-Matching in den Kern-Pipelines komplett.
• Dynamische Linguistische Mappings (Sekundär): Freitext-Negativregeln (negativeRules) und Farbzuordnungen werden niemals als Inline-Strings im Code verarbeitet, sondern dynamisch über die Multi-Language-Translations-Dateien (src/config/languages/) aufgelöst (getSemanticNegativeRuleExclusions(lang), getColorMap(lang)).
• Contrast Rules: Unterscheidungsmerkmale zu optisch ähnlichen Wesen.
• Relative Scale Ratios: Paarweise Größenverhältnisse (z. B. height_ratio: 0.65), um Proportionen in allen generierten Szenen konsistent zu halten.

3. Strikte Zero-Fallback-Garantie

In Produktions- und Test-Pipelines gilt das Prinzip absoluter Transparenz:

4. Automatisierte Erkennungs-Benchmark- & Regressions-Suite

Für kontinuierliche Qualitätskontrolle und automatisierte Regressions-Prüfung bietet Liberino eine dedizierte Benchmark-Suite (RecognitionBenchmarkService):

Funktionen:

• Golden Ground-Truth Fixtures (tests/fixtures/benchmarks/*.groundtruth.json): Szenenweise Definition von erwarteten Figuren/Objekten mit Mindestkonfidenzen und Bounding-Box-Flächengrenzen sowie explizit verbotenen Falscherkennungen (Forbidden Entities).
• Metriken: Präzise Auswertung von Precision, Recall, F1-Score, Regelverletzungen und Gesamt-Qualitäts-Score (0–100%).
• Historisches Delta-Tracking: Jeder Lauf vergleicht sich automatisch mit der vorherigen Messung in .benchmarks/recognition-history.json und visualisiert Verbesserungen (🟢), Verschlechterungen (🔴) und stabile Szenen (⚪).
• CLI & Test-Integration:

  # Interaktiver CLI Benchmark gegen die Datenbank
  npm run benchmark:recognition [bookId]
  
  # Automatisierte CI-Ausführung
  npx tsx --test tests/recognition-benchmark.test.ts

5. Buch-Snapshot-Testing & Szenen-Diff-Review

Zur systematischen Verifikation nach Modell-, Prompt- oder Algorithmus-Anpassungen ermöglicht das Snapshot-System (SnapshotTestingService) das Erfassen und Vergleichen von Buch-Mappings auf Szenenebene:

Workflow:

1. Baseline-Snapshot speichern:

   npm run snapshot:save [bookId]

   Erzeugt eine normalisierte JSON-Datei in tests/snapshots/<book-slug>.snapshot.json mit allen Kapiteln, Szenen, Bounding-Boxes, Figuren, Objekten und Koordinaten.

2. Diff prüfen (nach Änderungen oder Re-Import):

   npm run snapshot:diff [bookId]

   Erkennt granular:

   • ➕ Neu hinzugekommene Bounding-Boxes oder Figuren
   • ➖ Entfallene Bounding-Boxes
   • 🔄 Umetikettierte Figuren oder Objekte
   • 📐 Verschobene Box-Koordinaten (IoU & Silhouette)
   • 📊 Signifikante Konfidenz-Änderungen

3. Integrierter Re-Ingest mit automatischem Snapshot-Vergleich:

   npx tsx scripts/ingest-test-books.ts <book.epub> --snapshot

6. Algorithmisches Silhouette-Snapping & Relationale Alters-Inferenz

Algorithmisches Bounding-Box-Snapping & Kanten-Expansion (BoundingBoxRefinementService)

Grobe Bounding-Box-Vorschläge von multimodalen Vision-LLMs weisen durch Token-Quantisierung oft leichte Verschiebungen (z. B. 2–5% ins Leere oder abgeschnittene Füße/Arme) auf. Der deterministische Post-Processing-Refiner schließt diese Lücke direkt auf Pixelebene (0 API-Calls, 0 € Kosten):

1. Lokale Hintergrund-Schätzung: Extrahiert die Region of Interest (ROI) mit großzügigem Sicherheits-Padding (bis 65%) und schätzt die dominante Hintergrundfarbe der Umgebung über einen Außenrandstreifen.
2. Farbwolken- & Tuschekontur-Maskierung: Vergleicht Pixel über den euklidischen Farbabstand ($\Delta E \ge 24$) und dunkle Tuschelinien (Luminanz < 60) zum Hintergrund.
3. Farbbasierte direktionale Kanten-Expansion (Perimeter Probing): Prüft jede Kante (oben, unten, links, rechts) der Bounding-Box. Liegen Schnittkanten auf der Vordergrundfarbe des Motivs (Box schneidet durch den Körper), expandiert die Kante schrittweise nach außen, bis die Begrenzungslinie vollständig im freien Hintergrund liegt.
4. Deterministisches Silhouette-Snapping & Breathing-Padding: Zieht überschüssigen Weißraum passgenau an die äußere Kontur heran und addiert einen adaptiven Sicherheitsabstand (2.5% Breathing Padding), damit keine Zehen, Schwanz- oder Flügelspitzen an den Bildausschnittskanten kleben.
5. Full-Body Prompt-Direktive: Im System-Prompt des VisualEntityExtractionService erzwingt eine verbindliche Ganzkörper-Direktive die Erfassung der gesamten sichtbaren Anatomie (von Hörnern/Hut bis zu Füßen/Schwanz).

Relationale Peer-Kohorten-Altersinferenz (EntityExtractionService)

Anstelle isolierter Heuristiken nutzt die Pipeline probabilistisches Schließen über relationale Netzwerke:

• Peer-Kohorten-Propagierung: Charaktere, die gemeinsam reisen, ko-okkurrent in Szenen agieren und im Bild ähnliche Skalierungsverhältnisse aufweisen, bilden eine Alterskohorte. Wenn für eine Figur juvenile Attribute festgestellt werden („klein“, „Kind“, „junger Drache“), überträgt sich die Kategorie child auf die Gefährten.
• Asymmetrische Rollenhandlungen: Charaktere, die alleinige Schiffsnavigation, elterliche Fürsorge, Tabakspfeifen oder Lesebrillen tragen, werden als adult bzw. elder klassifiziert.

7. Robuste probabilistische Cross-Modale Architektur & Text-Anchoring

Entfernung harter Ausschluss-Schranken zugunsten von Soft-Penalties

Bisherige starre Ausschluss-Bedingungen (score: 0), die beispielsweise aquatische Wesen auf Booten oder Landtiere im Wasser sofort disqualifizierten, wurden durch ein graduelles Soft-Penalty-System abgelöst:

• Figuren können schwimmen, fliegen oder Boote betreten, ohne durch Habitat-Regeln fehlerhaft abgewiesen zu werden.
• Abzüge (-0.25 bis -0.50) werden probabilistisch gewichtet, sodass starke positive Evidenzen (Farbübereinstimmung, Szenen-Kookkurrenz, relative Proportionen) die Zuordnung robust stabilisieren.

Buchweite Frequenzverteilung & Text-Anchoring

Für jeden im Buch entdeckten Charakter, Requisite oder Ort wird automatisch die buchweite Texthäufigkeit über alle Kapitel ermittelt:

• Ungrounded Visual Noise Filtering: Bildobjekte oder Detektionen, die im gesamten Buchtext 0-mal genannt werden und keine Alias-Übereinstimmung besitzen, werden als irrelevantes Hintergrundrauschen eingestuft und nicht als Bounding Box persistiert.
• Häufig genannte Entitäten erhalten einen Kookkurrenz-Bonus, da sie narrativ von zentraler Relevanz sind.

Disambiguierung von Lookalikes & Geschlechter-Inferenz

Wenn zwei Charaktere derselben Spezies oder Statur ähnlich gezeichnet sind (z. B. Drachen-Elternpaare oder Geschwister):

1. Text-First: Analyse auf grammatikalisches Geschlecht über Eigennamen, Pronomen (er/sie) und Rollenbezeichnungen (Mutter/Vater, Freundin/Freund).
2. Visuelle Merkmale: Abgleich mit visuellen Gender-Merkmalen (Wimpern, Haare/Frisuren, Kleidung/Schürzen vs. Bart, Kahlheit, Hornkämme), wobei die explizite Textbeschreibung stets Vorrang vor visuellen Stereotypen hat.

Paarweise relationale Größenverifikation

Wurden zwischen Charakteren relationale Größenregeln etabliert (z. B. Figur A kleiner als Figur B):

• Erscheinen A und B gemeinsam in einer Illustration, wird die vertikale Ausdehnung der Bounding-Boxen verglichen.
• Steht die visuelle Größenrelation im Widerspruch zur Textregel ($H_A > 1.15 \cdot H_B$), greift ein zielgerichteter Penalty-Abzug.

8. Ganzheitliche narrative Timeline & Frühphasen-Fehlzuordnungs-Korrektur (VisualConsensusReconciliationService)

Wird ein Charakter zu Beginn eines Buches (z. B. in einer frühen Illustration) visuell fälschlicherweise einer Hauptfigur oder einem erst später im Text auftauchenden Charakter zugeordnet, löst die globale Consensus-Pipeline diesen Konflikt ganzheitlich über die gesamte Buch-Timeline:

graph TD
    TextScan[Buchweiter Volltext-Scan aller Szenen] --> DebutMap[Ermittlung des narrativen Debüt-Kapitels je Entität]
    DebutMap --> ConsensusProfiles[Kanonische Konsens-Profile nur aus narrativ gestützten Kapiteln]
    ConsensusProfiles --> OutlierCheck[Erkennung von Frühphasen-Fehlzuordnungen c < c_debut]
    OutlierCheck --> RetroactiveFix[Retroaktive Umbenennung auf den tatsächlichen Szenen-Akteur]
    RetroactiveFix --> SceneDisambig[Szenen-Disambiguierung bei doppelten Bounding Boxes]

1. Buchweites narratives Debüt-Tracking (entityDebutChapter)

• Vor der visuellen Auswertung wird das gesamte Buch semantisch und lexikalisch nach allen bekannten Entitätsnamen und deren Text-Synonymen durchsucht.
• Für jeden Charakter wird die exakte Menge der Kapitel ermittelt, in denen er im Text tatsächlich erwähnt wird (entityNarrativeChapters), sowie sein formales Debüt-Kapitel:

  debutChapter(e) = min { c | e in Text(c) }

2. Narrative-Supported Consensus Profile Building

• Visuelle Konsens-Profile (Farben, Silhouette, Attribute) werden primär aus Kapiteln gebildet, in denen die Entität auch narrativ durch den Text gestützt wird (c >= debutChapter).
• Frühe visuelle Fehlzuordnungen vor dem Text-Debüt können dadurch niemals das Referenzprofil der Entität verunreinigen.

3. Erkennung von Frühphasen-Fehlzuordnungen (Check 2)

• Tritt eine Detektion in einem Kapitel auf, das vor dem narrativen Debüt der Figur liegt (c < debutChapter), und wird die Figur im jeweiligen Szenen- oder Kapiteltext nicht erwähnt, prüft das System auf optische Unverträglichkeit mit dem späteren etablierten Konsens-Profil.
• Bei signifikantem visuellem Widerspruch (z. B. abweichende Primärfarben oder Größenrelationen) identifiziert das System die Box als Frühphasen-Fehlzuordnung.
• Die Szene-Text-Schutzplanke wird für diesen Fall gezielt deaktiviert: Die Box wird retroaktiv auf denjenigen Charakter umbenannt, der laut Text tatsächlich in der frühen Szene anwesend ist und optisch am besten übereinstimmt.

4. Disambiguierung gleichnamiger Duplikate pro Illustration (Check 4)

• Finden sich in einer einzelnen Illustration zwei Bounding-Boxes mit identischem Namen, obwohl die Figur ein einzigartiges Individuum ist und laut Text ein weiterer Charakter ko-präsent agiert, prüft das System spezifische Unterscheidungsmerkmale (z. B. getragene Requisiten, Nahrungsmittel oder Kopfbedeckungen).
• Die zutreffende Box wird dem noch unbesetzten ko-präsenten Text-Charakter mit hoher Konfidenz zugewiesen.

9. Interaktiver CLI-Import mit Vorab-Kalkulation & Live-Progress (npm run book:import)

Für automatisierte und redaktionelle Workflows stellt das System ein universelles CLI-Werkzeug bereit, das vollständig auf den API-Endpunkten des Backends aufsetzt:

# Buch-Import mit automatischer Vorab-Kalkulation und Live-Fortschrittsbalken
npm run book:import [pfad/zu/buch.epub]

1. Vorab-Kalkulation (POST /api/books/preflight)

Bevor persistierende Aktionen ausgeführt werden, analysiert die API das EPUB-Archiv rein im Arbeitsspeicher und liefert eine strukturierte Kostenschätzung:

• Token-Kalkulation: Aufschlüsselung in Eingabe-Tokens für Text (Wörter $\cdot 1.33$), Bild-Tokens (258 Tokens je Illustration bei Gemini Vision) und geschätzte Output-Tokens für Bounding Boxes und Metadaten.
• Modell-Preise: Direkte Umrechnung in Euro (€) und US-Dollar ($) für Gemini 2.5 Flash, Gemini 2.5 Pro und Bildgenerierung.
• Geschätzte Importdauer: Dynamisch berechnet anhand der Anzahl der Szenen und Illustrationen.

2. Live-Streaming-Ingest (POST /api/books/ingest/stream)

Die API streamt Fortschritts-Events über Server-Sent Events (SSE):

• Phasen 1 bis 6 werden mit exakter Prozentangabe (percentage), Statusmeldung (message) und Unterfortschritten (z. B. Bild $14/35$) in Echtzeit an den Aufrufer übertragen.
• Das CLI-Tool visualisiert den Fortschritt als flüssig aktualisierten Terminal-Fortschrittsbalken.