Charakter- & Entitäten-Pipeline API

Die Entitäten-Pipeline im liberino-ai-Backend übernimmt das Worldbuilding, die Figuren- und Schauplatzanalyse sowie die Synchronisation mit der Directus lore_entities-Collection. Sie entlastet das Frontend vollständig von schwerem Parsing, LLM-Chunking und multimodalen Bildabgleichen.

Endpunkt-Übersicht

1. Entitäten aus Text extrahieren (POST /api/entities/extract-from-text)

Analysiert Rohtext oder Kapitelabschnitte und identifiziert automatisch auftretende Charaktere, Artefakte und Schauplätze.

curl -X POST http://localhost:3005/api/entities/extract-from-text \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Es war einmal eine mutige junge Entdeckerin namens Mira. Sie lebte in der alten Hafenstadt zusammen mit ihrem treuen Begleiter Jaro...",
    "chunkSize": 4000,
    "persistToDirectus": true,
    "seriesId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
  }'

2. Dialog-Sprecher annotieren (POST /api/entities/annotate-dialogue)

Erkennt wörtliche Zitate anhand der sprachenspezifischen Anführungszeichen (quotePairs aus der jeweiligen Mapping-Datei, z. B. »...«, „...“ auf Deutsch, “...” auf Englisch) und annotiert den zugehörigen Sprecher aus der Ensemble-Liste.

curl -X POST http://localhost:3005/api/entities/annotate-dialogue \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<p>»Komm schnell mit, Jaro!«, rief Mira leise.</p>",
    "language": "de",
    "knownCharacters": [
      { "id": "char-mira", "name": "Mira" },
      { "id": "char-jaro", "name": "Jaro" }
    ]
  }'

Antwort:

{
  "success": true,
  "data": {
    "annotatedHtml": "<p><span speaker=\"char-mira\">»Komm schnell mit, Jaro!«</span>, rief Mira leise.</p>",
    "dialogueCount": 1,
    "annotatedCount": 1
  }
}

3. Illustrationen Entitäten zuordnen (POST /api/entities/map-images)

Führt eine multimodale Bild- und Metadaten-Analyse durch, um zu ermitteln, welche Charaktere, Artefakte oder Kulissen in einer Buchillustration abgebildet sind.

curl -X POST http://localhost:3005/api/entities/map-images \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "filename": "chapter_1.jpg",
        "base64": "data:image/jpeg;base64,...",
        "description": "Mira und Jaro am Waldrand"
      }
    ],
    "knownEntities": {
      "characters": [{ "id": "char-mira", "name": "Mira" }],
      "items": [{ "id": "item-messingkompass", "name": "Messingkompass" }],
      "locations": [{ "id": "loc-hafenstadt", "name": "Alte Hafenstadt" }]
    }
  }'

4. Turnaround-Prompts generieren (POST /api/entities/generate-prompt)

Erstellt maßgeschneiderte Generierungs-Prompts für Hero-Turnarounds (Vorder-, Seiten- und Rückansicht auf weißem Studiohintergrund).

curl -X POST http://localhost:3005/api/entities/generate-prompt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mira",
    "type": "character",
    "description": "Mutige junge Entdeckerin mit ledernem Rucksack und Fernrohr",
    "visualTraits": "Braunes schulterlanges Haar, Lederstiefel, Messingkompass",
    "styleModifier": "Clean 2D watercolor illustration, storybook art style"
  }'

5. Visuelle Merkmale rekonstruieren (POST /api/entities/reverse-prompt)

Extrahiert aus Bildern oder Beschreibungen ein standardisiertes visuelles Profil für konsistente Bildwiederholungen.

curl -X POST http://localhost:3005/api/entities/reverse-prompt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mira",
    "entityType": "characters",
    "images": ["data:image/png;base64,..."]
  }'

6. Visuelle Bounding-Box korrigieren (POST /api/entities/:id/refine-bbox)

Sendet ein Bild mit der bestehenden Bounding-Box an Gemini 2.5 Flash / Flash 3, um die Umrandung pixelgenau auf die Silhouette der Entität nachzuschärfen (z. B. Beine, Schweif oder Kopfbedeckungen einbeziehen).

curl -X POST http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/refine-bbox \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "http://localhost:3005/api/images/sample.jpg",
    "currentBox2d": [120, 240, 680, 520],
    "entityName": "Mira",
    "refinementPrompt": "Schärfe die Box nach, sodass die Stiefel und die Schalenden vollständig umfasst sind."
  }'

7. Rollenhierarchie aktualisieren (PATCH /api/entities/:id/tier)

Aktualisiert die Bedeutungsebene einer Lore-Entität in Directus (main für Hauptfiguren, supporting für Nebenrollen, extra für Statisten).

curl -X PATCH http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/tier \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "main"
  }'

8. Extrahierte Crops abrufen (GET /api/entities/:id/crops)

Gibt alle gespeicherten Bildausschnitte (Visual Crops) zurück, die dieser Entität während der Segmentierung und des Matchings zugeordnet wurden.

curl -X GET http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/crops

9. Entitäten zusammenführen (POST /api/entities/merge)

Führt ein oder mehrere Quell-Profile in ein Basisprofil zusammen (z. B. wenn mehrere Entitäten durch unterschiedliche Schreibweisen oder Synonyme denselben Charakter, Gegenstand oder Ort beschreiben).

Hierbei werden:

• Intelligente KI-Harmonisierung (synthesizeWithAi: true): Ein LLM-Konsens-Schritt destilliert die gemeinsamen Kernmerkmale (Invarianz) aller Profile, bereinigt temporäre Szenen-Aktionen und formuliert eine konsistente, kanonische Beschreibung.
• Regie-Anweisung mit höchster Priorität (userPrompt): Ein optionaler natürlicher Text wird vom LLM als vorrangige Regie-Vorgabe (Author Override) interpretiert und überschreibt widersprüchliche Angaben aus den Buch-Profilen gezielt.
• Synonyme, Erkennungsregeln, Negativregeln und Farbpaletten union-gemergt (ohne Duplikate).
• Visuelle Bildausschnitte (visual_segments) kombiniert.
• Szenen- und Kapitelvorkommen aggregiert.
• Szenen-Referenzen in illustration_metadata auf den kanonischen Namen aktualisiert.
• Alle Quell-Profile (sourceEntityIds oder abwärtskompatibel sourceEntityId) nach erfolgreicher Zusammenführung sauber aus Directus entfernt.

curl -X POST http://localhost:3005/api/entities/merge \
  -H "Content-Type: application/json" \
  -d '{
    "targetEntityId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "sourceEntityIds": [
      "a2c3e4f5-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
      "b3d4e5f6-2c3d-4e5f-6a7b-8c9d0e1f2a3b"
    ],
    "canonicalName": "Mira",
    "synthesizeWithAi": true,
    "userPrompt": "Mira trägt immer einen ledernen Rucksack und feste Stiefel, keine Mütze. Augenfarbe ist smaragdgrün."
  }'

9. Profil aktualisieren & anpassen (PATCH /api/entities/:id)

Ermöglicht das direkte Bearbeiten aller Stammdaten und static_traits einer Entität (z. B. Name, Typ, Rolle/Tier, Spezies, Altersstufe, Geschlecht, Flügel, Beschreibung, visuelle Merkmale und Kanon-Farben).

curl -X PATCH http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mira",
    "type": "character",
    "role_tier": "main",
    "species": "Mensch",
    "age_category": "child",
    "gender": "female",
    "special_features": ["Flügel", "Kompass"],
    "description": "Mutige junge Entdeckerin mit ledernem Rucksack.",
    "visualTraits": "Braune Haare, gelbe Mütze, rote Jacke",
    "exact_colors": "gelb, rot, braun"
  }'

10. Profil löschen (DELETE /api/entities/:id)

Löscht eine Entität unwiderruflich aus der Directus lore_entities-Collection. Bereinigt gleichzeitig alle Zuweisungen dieser Entität in den Bounding-Boxes der Szenen-Illustrationen (scenes.illustration_metadata).

curl -X DELETE http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

11. Einzel-Referenzkarte generieren (POST /api/entities/:id/generate-card)

Generiert eine maßgeschneiderte, typisierte kanonische Referenzkarte für ein einzelnes Profil (Charakter, Ort oder Objekt):

• Charaktere: Eine einzelne 4-Kachel-Grafik (1 Zeile, 4 Spalten: Von vorne, Von links, Von rechts, Von hinten) auf rein weißem Hintergrund (#ffffff), isoliert ohne störende Requisiten.
• Orte/Landschaften: 2 horizontale Kacheln (Totale Weitwinkelansicht oben, stimmungsvolle Nahaufnahme / Detail unten).
• Dinge/Objekte: 3 Spalten (Isolierte Gesamtansicht, Seiten-/Seitenprofil, Makro-Materialdetail).

Als allererstes Referenzbild (referenceImagesBase64[0]) wird eine strukturierte Schablone (Grid-Template) an das Vision-/Bildmodell übergeben, gefolgt von bis zu 5 ausgewählten Buch-Beispiel-Crops. Das Ergebnis wird persistent in Directus Files hochgeladen und in lore_entities.static_traits.canonical_card hinterlegt.

curl -X POST http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/generate-card \
  -H "Content-Type: application/json" \
  -d '{
    "selectedCrops": ["crop_uuid_1", "crop_uuid_2"]
  }'

12. Referenzkarte löschen (DELETE /api/entities/:id/reference-card)

Löscht die hinterlegte Referenzkarte aus dem static_traits-Dossier der Entität und entfernt die zugehörige Bilddatei unwiderruflich aus Directus Files.

curl -X DELETE http://localhost:3005/api/entities/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/reference-card