RAG-Prozess

Erstellt: 2025-12-24 | Aktualisiert: 2025-12-24

Dokument-Import (Phase 0-1)

Ziel

Ein Dokument wird kontrolliert übernommen, eindeutig identifiziert und unverändert archiviert. Der extrahierte Inhalt wird vollständig und reproduzierbar in der SQL-Datenbank als Single Source of Truth gespeichert.

Eingangskanäle

• Dateiupload über Content Pipeline UI
• Ablage in beobachtetem Import-Verzeichnis
• Übergabe über interne Schnittstelle

Akzeptierte Formate

• PDF (via pdfplumber)
• Markdown
• Plain Text

Identität und Versionierung

Archivierung

Die Originaldatei wird unverändert archiviert und dient als Quelle für Reprocessing:

• Binärartefakt
• Content Hash
• Dateigröße
• Erfassungszeit

Textgewinnung

• Formatabhängige, deterministische Extraktion
• Linearer Textstrom ohne Layoutlogik
• Keine Inhalte entfernt, zusammengefasst oder interpretiert

Normalisierung

• Vereinheitlichung von Zeilenumbrüchen
• Unicode-Normalisierung
• Entfernung technischer Steuerzeichen

Beteiligte Komponenten

Datenbank-Schema

documents:
  id, filename, source_path, file_size, content_hash,
  page_count, status, version, created_at

document_pages:
  id, document_id, page_number, content, 
  metadata, created_at

Prüfbedingungen für Supervision

• Für jede Dokumenten-ID existiert mindestens eine unveränderte Originaldatei
• Jede spätere Verarbeitung referenziert exakt diese Dokumenten-ID und Version
• Reprocessing mit derselben Originaldatei ergibt identische Content Hash Werte
• Der gespeicherte Text ist vollständig aus der Originaldatei rekonstruierbar

Erstellt: 2025-12-24 | Aktualisiert: 2025-12-24

Chunking (Phase 2-3)

Ziel

Der gespeicherte Volltext wird in explizite Struktureinheiten zerlegt und daraus technisch handhabbare Verarbeitungseinheiten (Chunks) erzeugt. Chunking ist eine technische Maßnahme, keine semantische Interpretation.

Phase 2: Strukturelle Zerlegung

Seitenzerlegung

• Text wird in Seiten zerlegt (sofern Ursprungsformat Seiten kennt)
• Eindeutige und stabile Seitenreihenfolge
• Jede Seite erhält: Seiten-ID, Position, Dokument-Referenz

Semantische Abschnitte

• Kapitel und Überschriftenbereiche
• Logisch zusammenhängende Sinnblöcke
• Erkennung über explizite Überschriftenstrukturen und formale Marker

Phase 3: Chunk-Erzeugung

Chunking-Regeln

Erzeugungsregeln

• Jeder Chunk entsteht aus genau einem Abschnitt
• Ein Abschnitt kann mehrere Chunks erzeugen
• Kein Chunk überschreitet Abschnittsgrenzen
• Erhalt vollständiger Sätze

Semantische Rolle

Jedem Chunk wird eine semantische Rolle zugewiesen:

• Fließtext
• Definition
• Aufzählung
• Beispiel
• Sonstiges

Chunk-Metadaten

• Stabile Chunk-ID (unabhängig von Speicherung in anderen Systemen)
• Referenz auf Dokumenten-ID und Abschnitts-ID
• Positionsangabe innerhalb des Abschnitts
• Vollständiger Chunk-Text
• Token-Count und Heading-Path

Beteiligte Komponenten

Datenbank-Schema

chunks:
  id, document_id, section_id, chunk_index, content,
  token_count, heading_path, semantic_role, metadata,
  qdrant_id, created_at

Prüfbedingungen für Supervision

• Jeder Chunk ist exakt einem Abschnitt zugeordnet
• Kein Chunk überschreitet Abschnittsgrenzen
• Chunk-Erzeugung ist reproduzierbar bei identischem Input
• Alle Chunks sind in der SQL-Datenbank vollständig gespeichert (nicht nur in Qdrant!)

Erstellt: 2025-12-24 | Aktualisiert: 2025-12-24

Embedding-Generierung

Funktion

• Text-Chunks in numerische Vektorrepräsentationen umwandeln
• Semantische Bedeutung in 1536-dimensionalem Vektor kodieren
• Ermöglicht Ähnlichkeitssuche via Cosine-Similarity

Eingabe

• Chunk-Text aus chunks-Tabelle
• Maximal 800 Zeichen pro Chunk (Modell-Limit)

Ausgabe

• Vektor mit 1536 Float-Werten
• Normalisiert für Cosine-Similarity

Embedding-Modell

Beteiligte Komponenten

Ablauf

1. Chunk-Text laden
2. Text bereinigen (Punktfolgen reduzieren)
3. Auf 800 Zeichen truncaten falls nötig
4. POST an Ollama /api/embeddings
5. Vektor aus Response extrahieren
6. Weiter an Vektorspeicherung

Code-Beispiel

# pipeline/embed.py
def get_embedding(text):
    response = requests.post(
        f"{OLLAMA_HOST}/api/embeddings",
        json={"model": EMBEDDING_MODEL, "prompt": text},
        timeout=60
    )
    return response.json().get("embedding")

Fehlerbehandlung

• Leerer Text → None zurückgeben, überspringen
• Timeout → Logging, Retry
• Ollama nicht erreichbar → Fehler loggen, Chunk als pending belassen

Vektorspeicherung (Phase 4)

Ziel

Chunks werden in einen mathematischen Ähnlichkeitsraum überführt. Die Vektordatenbank dient ausschließlich dem Auffinden inhaltlich ähnlicher Chunks. Sie ist kein Wissensspeicher und trägt keine semantische Wahrheit.

Vektorisierung

• Jeder Chunk wird genau einmal eingebettet pro Modellversion
• Einbettung mit festgelegtem, versioniertem Embedding-Modell
• Keine semantische Anreicherung vor der Einbettung
• Modellversion und Parameter werden dokumentiert

Qdrant-Konfiguration

Payload-Struktur (erlaubt)

{
  "chunk_id": 1234,
  "document_id": 42,
  "section_id": 15,
  "language": "de",
  "document_type": "pdf"
}

Payload enthält KEINE

• Entitäten
• Relationen
• Aussagen
• Ontologie- oder Taxonomieelemente
• Provenienzinformationen

Rolle der Vektordatenbank

Abgrenzung zur Semantik

• Die Vektordatenbank enthält keine Bedeutung
• Sie kennt keine Wahrheit, keine Gültigkeit, keine Herkunft
• Ähnlichkeit ist kein Wissensbegriff, sondern ein Distanzmaß
• Semantische Interpretation erfolgt ausschließlich in späteren Phasen

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Jeder gespeicherte Vektor referenziert exakt einen Chunk
• Kein Chunk besitzt mehr als einen Vektor pro Modellversion
• Die Vektordatenbank enthält keine inhaltlichen oder semantischen Daten
• Löschung eines Chunks erzwingt Löschung des referenzierten Vektors

Anfrage-Verarbeitung (Phase A0-A1)

Grundsatz

Der Abfrageprozess ist kein Spiegel der Importpipeline. Er ist ein konsumierender Prozess, der ausschließlich auf bereits validierten, versionierten Zuständen arbeitet.

• Die Abfrage erzeugt kein Wissen
• Sie kombiniert, filtert und formuliert vorhandene Information
• Der Graph wird nicht verändert
• Die SQL-Datenbank bleibt kanonisch
• Die Vektordatenbank wird nur zur Vorselektion genutzt

Phase A0: Anfrage-Eingang und Kontextdefinition

Ziel

Eindeutige Definition dessen, was gefragt wird und in welchem Rahmen.

Ablauf

1. Eine Anfrage wird vom Nutzer über eine Anwendung initiiert:
   • KI-Chat
   • Content Studio
2. Die Anfrage besteht aus:
   • Primärfrage oder Briefing
   • Anwendungs-Kontext
   • optionalen Parametern
3. Kontextparameter sind explizit:
   • Ziel-Collection(s)
   • gewünschte Kontext-Tiefe (top_k)
   • Modellwahl
   • Token-Limits
4. Die Anfrage wird als Abfrageobjekt behandelt, nicht als Textfragment

Ergebnisartefakte

• Anfrage-ID
• Roh-Anfragetext
• Abfragekonfiguration

Phase A1: Anfrage-Einbettung

Ziel

Überführung der Anfrage in einen Suchvektor für Ähnlichkeitsretrieval.

Ablauf

1. Der Anfragetext wird technisch normalisiert
2. Die Anfrage wird mit demselben Embedding-Modell eingebettet wie die Chunks
3. Es entsteht genau ein Query-Vektor

Abgrenzung

• Keine semantische Analyse
• Keine Interpretation
• Keine Graph-Abfrage

Ergebnisartefakte

• Query-Vektor (1536 Dimensionen)
• Referenz auf verwendetes Embedding-Modell

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Die Anfrage ist vollständig parametriert, bevor irgendein Retrieval beginnt
• Modellidentität zwischen Indexierung und Anfrage ist geprüft
• Query-Vektor verwendet exakt dasselbe Modell wie Chunk-Vektoren

Vektorbasierte Vorselektion (Phase A2)

Ziel

Reduktion des Suchraums auf potenziell relevante Chunks. Dies ist eine Vorselektion, keine Wahrheitsfindung.

Ablauf

1. Der Query-Vektor wird gegen die definierte Collection gesucht
2. Die Vektordatenbank liefert:
   • Chunk-Referenzen (IDs)
   • Relevanz-Scores (Cosine Similarity)
3. Es werden ausschließlich Chunk-IDs und Payload-Metadaten verwendet
4. Anzahl der Ergebnisse wird durch top_k begrenzt

Kritische Abgrenzung

Ähnlichkeit ≠ Relevanz ≠ Wahrheit

Qdrant-Abfrage

POST /collections/documents/points/search
{
  "vector": [0.123, -0.456, ...],  // 1536 Dimensionen
  "limit": 10,
  "with_payload": true,
  "filter": {
    "must": [
      {"key": "collection", "match": {"value": "documents"}}
    ]
  }
}

Ergebnisartefakte

• Kandidatenliste von Chunk-IDs mit Scores
• Sortiert nach absteigendem Score

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Kein Chunk ohne SQL-Referenz gelangt weiter
• Score-Werte werden protokolliert, aber nicht als Wahrheit behandelt
• Die Vektordatenbank liefert nur IDs, kein Content wird vertraut

Kontext-Aufbau (Phase A4-A5)

Phase A4: Kontext-Selektion und Priorisierung

Ziel

Zusammenstellung eines sinnvollen, begrenzten Arbeitskontextes aus den nachgeladenen Chunks.

Ablauf

1. Chunks werden priorisiert nach:
   • Relevanz-Score (aus Vorselektion)
   • Dokumentenvielfalt (nicht alle Chunks aus einem Dokument)
   • Redundanzfreiheit (keine inhaltlichen Dopplungen)
2. Auswahl erfolgt bis zum:
   • Token-Limit (Modell-abhängig)
   • Kontext-Limit (konfiguriert als top_k)
3. Reihenfolge wird festgelegt und stabilisiert

Abgrenzung

• Noch keine Textgenerierung
• Keine semantische Umformung
• Reine Selektion und Ordnung

Ergebnisartefakte

• Geordnete Chunk-Liste für Kontext
• Token-Summe des Kontexts

Phase A5: Kontext-Formalisierung

Ziel

Übersetzung der ausgewählten Chunks in ein LLM-verwertbares Kontextformat.

Ablauf

1. Jeder Chunk wird versehen mit:
   • Quellenkennzeichnung (z.B. [Quelle 1])
   • Dokumentenreferenz (Dateiname, Seite)
2. Trennmarker werden eingefügt zwischen Chunks
3. Token-Limits werden technisch geprüft

Kontextformat

[Quelle 1: Systemisches Coaching.pdf, S. 12]
Die Auftragsklärung ist der erste Schritt im Coaching-Prozess...

---

[Quelle 2: Methodenhandbuch.pdf, S. 45]
Skalenfragen ermöglichen eine differenzierte Einschätzung...

---

[Quelle 3: Grundlagen der Systemik.pdf, S. 8]
Ressourcenorientierung bedeutet, den Fokus auf vorhandene Stärken...

Ergebnisartefakte

• Formatierter Kontextblock
• Quellenliste mit Referenzen
• Token-Count des finalen Kontexts

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Kontextaufbau ist deterministisch nachvollziehbar
• Jede Kontextpassage ist eindeutig einer Quelle zugeordnet
• Token-Limit wird nicht überschritten
• Quellenliste ist vollständig und korrekt

Kanonisches SQL-Nachladen (Phase A3)

Ziel

Rückführung der vorselektierten Chunks in den kanonischen Datenbestand. Ab dieser Phase spielt die Vektordatenbank keine Rolle mehr.

Grundprinzip

Kein Vertrauen in Payload-Content. Die Vektordatenbank liefert nur IDs. Der tatsächliche Content wird ausschließlich aus der SQL-Datenbank geladen.

Ablauf

1. Für jede Chunk-ID werden aus der SQL-Datenbank geladen:
   • Chunk-Text (vollständig)
   • Dokumenten-Referenz
   • Abschnitts-Referenz
   • Provenienzinformationen
2. Die Vektordatenbank spielt keine Rolle mehr
3. SQL ist alleinige Quelle der Wahrheit

SQL-Abfrage

SELECT 
    c.id, c.content, c.heading_path, c.token_count,
    d.id AS document_id, d.filename, d.source_path,
    dp.page_number
FROM chunks c
JOIN documents d ON c.document_id = d.id
LEFT JOIN document_pages dp ON c.page_id = dp.id
WHERE c.id IN (?, ?, ?, ...)

Warum nicht direkt aus Qdrant-Payload?

Ergebnisartefakte

• Vollständige Chunk-Datensätze
• Dokumenten-Metadaten
• Provenienz-Informationen

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Jeder verwendete Text ist aus SQL rekonstruierbar
• Kein Content aus Qdrant-Payload wird direkt verwendet
• Alle Chunks haben valide Dokumenten-Referenzen
• Fehlende Chunks in SQL führen zum Ausschluss (nicht zur Nutzung von Payload)

LLM-Generierung (Phase A7)

Ziel

Erzeugung einer Antwort auf Basis des bereitgestellten Kontextes. Das LLM ist reiner Formulierer, kein Wissensproduzent.

Grundprinzip

• LLM erzeugt Text, kein Wissen
• Wahrheit liegt weiterhin im System, nicht im Output
• Das LLM kombiniert und formuliert, erfindet nicht

Ablauf

1. Prompt wird an das gewählte LLM übergeben
2. LLM generiert Text innerhalb:
   • Token-Limit (max_tokens)
   • Temperature (Kreativität vs. Präzision)
   • Systemregeln (aus System-Prompt)
3. Ausgabe wird nicht verändert oder nachbearbeitet

Modell-Konfiguration

API-Aufruf (Claude)

POST https://api.anthropic.com/v1/messages
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 4096,
  "system": "Du bist ein hilfreicher Assistent...",
  "messages": [
    {"role": "user", "content": "[Kontext]\n...\n[Frage]\n..."}
  ]
}

Ergebnisartefakte

• Roh-Antworttext
• Token-Verbrauch (input + output)
• Modell-Referenz
• Latenz

Beteiligte Komponenten

Prüfbedingungen für Supervision

• LLM hat ausschließlich den bereitgestellten Kontext genutzt
• Antwort enthält keine Informationen außerhalb des Kontexts
• Token-Verbrauch ist protokolliert
• Modellversion ist dokumentiert

Prompt-Komposition (Phase A6)

Ziel

Zusammenführung von Kontext, Anfrage und Steuerinformationen zu einem vollständigen, reproduzierbaren Prompt.

Ablauf

1. System-Prompt definiert:
   • Rolle des Assistenten
   • Verhaltensregeln
   • Antwortgrenzen und -format
2. Kontext-Block enthält:
   • Formatierte Chunks mit Quellenreferenzen
   • Trennmarker
3. User-Prompt enthält:
   • Originalfrage oder Briefing
   • Eventuell Anweisungen zur Antwortstruktur

Prompt-Struktur

┌─────────────────────────────────────┐
│ SYSTEM-PROMPT                       │
│ - Rolle: "Du bist ein Assistent..." │
│ - Regeln: "Antworte nur basierend   │
│   auf den bereitgestellten Quellen" │
│ - Format: "Strukturiere deine       │
│   Antwort mit Überschriften"        │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ KONTEXT                             │
│ [Quelle 1: ...]                     │
│ Text aus Chunk 1...                 │
│ ---                                 │
│ [Quelle 2: ...]                     │
│ Text aus Chunk 2...                 │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ USER-PROMPT                         │
│ "Erkläre mir die Auftragsklärung    │
│ im systemischen Coaching."          │
└─────────────────────────────────────┘

Kritische Abgrenzung

• Keine inhaltliche Erweiterung des Kontexts
• Keine semantische Anreicherung
• Kontext wird nicht verändert, sondern eingebettet

Anwendungsspezifische Varianten

Ergebnisartefakte

• Vollständiger Prompt (System + Kontext + User)
• Token-Count des Gesamtprompts

Beteiligte Komponenten

Prüfbedingungen für Supervision

• Prompt ist vollständig rekonstruierbar
• System-Prompt enthält keine halluzinierten Inhalte
• Kontext ist unverändert eingebettet
• Token-Limit des Modells wird respektiert

KI-Chat Anwendung (Phase A8)

Ziel

Nachvollziehbare Übergabe der Antwort an den Nutzer mit vollständiger Quellenrückverfolgung.

Grundprinzip: Transparenz als Prozessbestandteil

Transparenz ist kein UI-Feature, sondern Prozessbestandteil. Jede Antwort ist auf ihre Quellen rückführbar.

Ablauf

1. Antwort wird in der Chat-Oberfläche angezeigt
2. Verwendete Quellen werden explizit ausgewiesen
3. Speicherung in Session:
   • Nachricht (Frage + Antwort)
   • Verwendete Chunks
   • Modell und Token-Verbrauch
4. Session kann exportiert werden (JSON/Markdown)

Session-Struktur

chat_sessions:
  id (UUID), title, model, created_at, updated_at

chat_messages:
  id, session_id, role (user/assistant), 
  content, created_at

chat_sources:
  id, message_id, chunk_id, document_id,
  relevance_score, document_name

Quellenanzeige

Jede Antwort zeigt die verwendeten Quellen:

┌────────────────────────────────────┐
│ Antwort des Assistenten            │
│ ...                                │
├────────────────────────────────────┤
│ Quellen:                           │
│ [1] Systemisches Coaching.pdf, S.12│
│ [2] Methodenhandbuch.pdf, S.45     │
│ [3] Grundlagen der Systemik.pdf    │
└────────────────────────────────────┘

Beteiligte Komponenten

Datenbank

• ki_content.chat_sessions
• ki_content.chat_messages
• ki_content.chat_sources

Export-Formate

Prüfbedingungen für Supervision

• Jede Antwort ist auf ihre Quellen rückführbar
• Session-Historie ist vollständig persistiert
• Quellenreferenzen zeigen auf valide Dokumente
• Export enthält alle relevanten Metadaten

Semantische Roh-Extraktion (Phase 5)

Ziel

Aus Chunk-Texten werden bedeutungstragende Elemente erkannt. Diese Phase dient der vollständigen Erfassung potenzieller semantischer Signale. Korrektheit, Konsistenz und Vereinheitlichung sind ausdrücklich nicht Ziel dieser Phase.

Eingangsbasis

• Grundlage sind ausschließlich die Chunk-Texte aus Phase 3
• Die Analyse erfolgt chunkweise, ohne Kenntnis anderer Chunks
• Es findet keine globale Konsolidierung statt

Analyseverfahren

Chunk-Texte werden mit festgelegten, versionierten Verfahren verarbeitet:

• Named Entity Recognition (NER) - Erkennung benannter Entitäten
• Relation Extraction - Extraktion expliziter Beziehungen
• Aussage- und Prädikaterkennung - Identifikation von Behauptungen

Entitätsextraktion

Alle erkennbaren Entitäten werden extrahiert:

Wichtig

• Es wird nicht geprüft, ob Entitäten bereits existieren
• Mehrfachnennungen und Varianten werden nicht zusammengeführt
• Das ist Aufgabe der nächsten Phase (Normalisierung)

Relationsextraktion

• Explizit im Text genannte Relationen werden extrahiert
• Implizite oder logisch abgeleitete Relationen werden nicht ergänzt
• Relationen werden ohne Typisierungstiefe erfasst

Roh-Aussagen

Textuelle Aussagen werden als Rohformen identifiziert:

{
  "subject": "Systemisches Coaching",
  "predicate": "basiert auf",
  "object": "konstruktivistischer Grundhaltung"
}

• Modalität, Gültigkeit und Kontext werden noch nicht bewertet
• Aussagen können unvollständig oder widersprüchlich sein

Temporärer Status

• Ergebnisse dieser Phase sind temporär
• Sie werden nicht als Wahrheit betrachtet
• Sie werden nicht als stabil gespeichert
• Sie dienen ausschließlich als Input für Konsolidierung

Abgrenzung zur Persistenz

• In dieser Phase findet keine dauerhafte Speicherung im Wissensbestand statt
• Es werden keine stabilen IDs vergeben
• Es erfolgt keine Zuordnung zur Ontologie

Ergebnisartefakte

• Roh-Entitäten pro Chunk
• Roh-Relationen pro Chunk
• Roh-Aussagen pro Chunk

Prüfbedingungen für Supervision

• Kein extrahiertes Element gilt als gültig oder korrekt
• Wiederholte Analyse desselben Chunks liefert strukturell vergleichbare Rohdaten
• Kein Roh-Element ist ohne Chunk-Referenz vorhanden

Content Studio Anwendung (Phase A8)

Ziel

Strukturierte Content-Erstellung mit RAG-gestützter Generierung, Kritik-Runden und Versionierung.

Workflow-Phasen

1. Auftrag erstellen - Briefing definieren
2. Content generieren - RAG-basierte Erstgenerierung
3. Kritik-Runde - Automatisierte Qualitätsprüfung
4. Revision - Überarbeitung basierend auf Kritik
5. Freigabe - Genehmigung oder Ablehnung

Auftrag-Struktur

content_orders:
  id, title, briefing, status,
  model, collections, context_limit,
  profile_id, contract_id, structure_id,
  created_at, updated_at

Versionierung

Jede Generierung erzeugt eine neue Version:

content_versions:
  id, order_id, version_number,
  content, model_used,
  tokens_input, tokens_output,
  created_at

Kritik-System

Automatisierte Qualitätsprüfung durch konfigurierte Kritiker:

Kritik-Ergebnis

content_critiques:
  id, version_id, critic_name, round,
  rating, passed, issues, suggestions,
  summary, created_at

Quellen-Tracking

Alle verwendeten RAG-Quellen werden persistiert:

content_sources:
  id, version_id, chunk_id, document_id,
  document_name, relevance_score

Status-Flow

draft → generate → critique → revision → validate → approved
                      ↓                      ↓
                   revision              declined

Beteiligte Komponenten

Datenbank

• ki_content.content_orders
• ki_content.content_versions
• ki_content.content_critiques
• ki_content.content_sources

Prüfbedingungen für Supervision

• Jede Version ist auf ihre Quellen rückführbar
• Kritik-Historie ist vollständig dokumentiert
• Revisionen referenzieren die zugrundeliegende Kritik
• Token-Verbrauch ist pro Version protokolliert
• Status-Übergänge sind nachvollziehbar

Normalisierung und Konsolidierung (Phase 6)

Ziel

Aus temporären Rohdaten entsteht ein konsistenter, referenzierbarer Wissensbestand. Diese Phase überführt extrahierte Signale in stabile Entitäten und Relationen. Ab hier beginnt semantische Verlässlichkeit.

Eingangsbasis

• Grundlage sind ausschließlich die Rohdaten aus Phase 5
• Rohdaten behalten ihren Bezug zu Chunk, Abschnitt und Dokument
• Keine neuen semantischen Elemente werden hinzugefügt

Normalisierung von Entitäten

Entitäten werden sprachlich und formal normalisiert:

Normalisierung verändert die Darstellung, nicht die Bedeutung.

Koreferenzauflösung

• Es wird geprüft, ob verschiedene Roh-Entitäten dieselbe reale Entität bezeichnen
• Kriterien für Gleichheit sind dokumentiert und reproduzierbar
• Gleiche Entitäten werden zu einer kanonischen Entität zusammengeführt
• Unterschiedliche Entitäten bleiben getrennt, auch wenn sie ähnlich sind

Vergabe stabiler Identitäten

Konsolidierung von Relationen

• Roh-Relationen werden geprüft und vereinheitlicht
• Relationstypen werden auf einen kontrollierten Satz abgebildet
• Unzulässige oder unklare Relationen werden verworfen oder markiert
• Relationen referenzieren ausschließlich stabile Entity-IDs

Dublettenerkennung und Bereinigung

• Doppelte Entitäten und Relationen werden identifiziert
• Dubletten werden zusammengeführt oder entfernt
• Der Vorgang ist nachvollziehbar und reversibel

Persistenz

• Erst nach Abschluss aller Prüfungen erfolgt Persistenz
• Persistiert werden: konsolidierte Entitäten und validierte Relationen
• Persistenz erfolgt in der SQL-Datenbank als kanonischer Quelle

Abgrenzung zur Ontologie

• In dieser Phase erfolgt keine Klassenzuordnung
• Ontologische Einordnung ist Gegenstand von Phase 8

Ergebnisartefakte

• Stabile Entitäten mit Entity-ID
• Konsolidierte Relationen
• Bereinigter Wissensrohbestand

Prüfbedingungen für Supervision

• Jede persistierte Entität besitzt genau eine stabile Entity-ID
• Keine persistierte Relation referenziert Roh-Entitäten
• Alle Zusammenführungen sind nachvollziehbar dokumentiert

Semantische Aussagen als Graphkern (Phase 7)

Ziel

Explizite Bedeutung entsteht. Diese Phase bildet den eigentlichen Wissenskern des Systems. Der Graph entsteht hier als Datenmodell, unabhängig von der konkreten Speichertechnologie.

Grundprinzip

• Wissen wird nicht aus Entitäten allein gebildet, sondern aus Aussagen
• Eine Aussage ist eine überprüfbare semantische Einheit
• Der Graph entsteht aus der Gesamtheit dieser Aussagen

Modellierung von Aussagen

• Jede Aussage wird als eigenständiges Objekt modelliert
• Aussagen sind keine impliziten Kanten, sondern explizite Datensätze
• Jede Aussage besitzt eine eigene stabile Aussage-ID

Bestandteile einer Aussage

Aussage-Typ

Der Aussage-Typ beschreibt die Art der Behauptung:

• Definition - "X ist definiert als Y"
• Faktische Behauptung - "X hat Eigenschaft Y"
• Regel - "Wenn X, dann Y"
• Beschreibung - "X wird beschrieben durch Y"
• Beispiel - "X ist ein Beispiel für Y"

Der Typ beeinflusst nicht den Wahrheitsgehalt, sondern die Interpretierbarkeit.

Kontext

Der Kontext beschreibt die Geltungsbedingungen der Aussage:

• Thematischer Rahmen (z.B. "Systemisches Coaching")
• Zeitlicher Bezug (z.B. "Stand 2024")
• Fachlicher oder organisatorischer Geltungsraum

Kontext ist explizit modelliert und nicht implizit aus dem Text abzuleiten.

Modalität

Die Modalität beschreibt den Aussagecharakter:

• behauptend - "X ist Y"
• einschränkend - "X ist manchmal Y"
• hypothetisch - "X könnte Y sein"
• normativ - "X sollte Y sein"
• zitierend - "Laut Z ist X Y"

Modalität macht Aussagen vergleichbar und widerspruchsfähig.

Graphbildung

• Jede Aussage erzeugt einen expliziten Graphzusammenhang
• Entitäten sind Knoten
• Aussagen sind strukturierte Beziehungseinheiten
• Relationen sind Bestandteil der Aussage, nicht ihr Ersatz

Abgrenzung

• Entitäten allein tragen keine Bedeutung
• Relationen allein sind nicht überprüfbar
• Erst Aussagen machen Bedeutung explizit und handhabbar

Persistenz

• Aussagen werden persistent in der SQL-Datenbank gespeichert
• Aussagen referenzieren ausschließlich stabile Entity-IDs
• Aussagen sind versionierbar und korrigierbar

Prüfbedingungen für Supervision

• Keine Aussage existiert ohne explizite Entitätenreferenz
• Jede Aussage besitzt genau einen Typ, einen Kontext und eine Modalität
• Aussagen können unabhängig voneinander geprüft und geändert werden

Ontologie (Phase 8)

Ziel

Entitäten und Aussagen werden in ein explizites Weltmodell eingeordnet. Die Ontologie definiert die begriffliche Struktur dessen, was im System existieren darf. Sie schafft semantische Stabilität über einzelne Dokumente hinaus.

Grundprinzip

• Die Ontologie beschreibt Klassen, nicht konkrete Einzelfälle
• Entitäten sind Instanzen von Ontologie-Klassen
• Aussagen referenzieren implizit die Ontologie über ihre beteiligten Entitäten

Ontologie-Klassen

Ontologie-Klassen werden explizit modelliert:

Klassen besitzen keine Textfragmente und keine Dokumentabhängigkeit.

Beispiel-Ontologie (Systemisches Coaching)

Coaching-Konzept
├── Methode (z.B. Auftragsklärung, Zielarbeit)
├── Haltung (z.B. Ressourcenorientierung, Wertschätzung)
├── Intervention (z.B. Skalenfrage, Wunderfrage)
└── Kontext (z.B. Einzelcoaching, Teamcoaching)

Person
├── Coach
├── Klient
└── Auftraggeber

Zuordnung von Entitäten

• Jede konsolidierte Entität wird mindestens einer Ontologie-Klasse zugeordnet
• Mehrfachzuordnungen sind zulässig, sofern fachlich begründet
• Die Zuordnung ist explizit gespeichert und nachvollziehbar

Stabilität und Erweiterung

• Bestehende Klassen werden nicht überschrieben
• Änderungen erfolgen durch:
  • Ergänzung neuer Klassen
  • Präzisierung durch neue Versionen
• Alte Klassenversionen bleiben referenzierbar

Abgrenzung zur Taxonomie

Abgrenzung zur Semantik

• Ontologie legt Begriffe fest, nicht Bedeutung im Kontext
• Die Bedeutung einer Aussage entsteht durch Phase 7
• Ontologie und Semantik sind komplementär, nicht austauschbar

Persistenz

• Ontologie-Klassen werden in der SQL-Datenbank gespeichert
• Klassenreferenzen sind stabil über Dokument- und Entitätsversionen
• Änderungen an der Ontologie sind versioniert und nachvollziehbar

Ergebnisartefakte

• Versionierte Ontologie-Klassen
• Explizite Zuordnung von Entitäten zu Klassen
• Konsistentes begriffliches Weltmodell

Prüfbedingungen für Supervision

• Jede Entität ist mindestens einer Ontologie-Klasse zugeordnet
• Keine Klasse wird implizit aus Text abgeleitet
• Ontologie-Änderungen sind versioniert und rückverfolgbar

Taxonomie (Phase 9)

Ziel

Ontologie-Klassen werden in eine explizite Ordnungsstruktur gebracht. Die Taxonomie definiert Hierarchien und Zugehörigkeiten zwischen Klassen. Sie dient der Navigation, Aggregation und systematischen Einordnung.

Grundprinzip

• Die Taxonomie operiert ausschließlich auf Ontologie-Klassen
• Sie ordnet Klassen, nicht Entitäten und nicht Aussagen
• Taxonomische Beziehungen sind strukturierend, nicht interpretierend

Taxonomische Beziehungen

Erlaubte Beziehungstypen sind explizit definiert:

Andere Beziehungstypen sind in der Taxonomie nicht zulässig.

Aufbau der Hierarchie

• Ontologie-Klassen werden hierarchisch eingeordnet
• Zyklen sind unzulässig
• Mehrfachvererbung ist nur erlaubt, wenn fachlich begründet
• Die Hierarchie ist vollständig explizit gespeichert

Implementierung: Taxonomie-Mapping (2025-12-25)

Übersicht

Die Taxonomie-Mapping-Komponenten ermöglichen die Zuordnung von Chunks und Entities zu Taxonomie-Begriffen. Dies erweitert die klassische Taxonomie um eine semantische Verknüpfungsschicht.

Domain Layer

Repository Interfaces

UseCases

Python Pipeline Integration

Die Pipeline erweitert die Analyse um automatische Taxonomie-Zuweisungen:

# db.py - Neue Funktionen
db.add_chunk_taxonomy(chunk_id, term_id, confidence, source)
db.get_chunk_taxonomies(chunk_id)
db.add_entity_taxonomy(entity_id, term_id, relevance, validated)
db.get_entity_taxonomies(entity_id)
db.get_taxonomy_terms()

# document_analyzer.py - Neue Funktionen
propagate_taxonomy_to_chunks(document_id, taxonomy)
assign_entity_taxonomy(document_id, entities, taxonomy)

Datenfluss

Dokument-Analyse
      │
      ▼
┌─────────────────────────────────────────┐
│ classify_taxonomy() → document_taxonomy │
└─────────────────────┬───────────────────┘
                      │
        ┌─────────────┴─────────────┐
        ▼                           ▼
┌───────────────────┐    ┌────────────────────┐
│ propagate_to_     │    │ assign_entity_     │
│ chunks()          │    │ taxonomy()         │
│ → chunk_taxonomy  │    │ → entity_taxonomy_ │
│                   │    │   mapping          │
└───────────────────┘    └────────────────────┘

Contract: taxonomy-mapping-contract

Qualitätsregeln für Taxonomie-Mappings (Contract ID: 12):

• TMC-001: Chunk-Mappings: Confidence ∈ [0.0, 1.0]
• TMC-002: Chunk-Mappings: Source ∈ {auto, manual}
• TMC-003: Entity-Mappings: Relevance ∈ [0.0, 1.0]
• TMC-004-006: Referentielle Integrität (Chunks, Entities, Terms)

Beispiel-Taxonomie

Coaching-Konzept (Wurzel)
├── ist-ein → Methode
│   ├── ist-ein → Auftragsklärung
│   ├── ist-ein → Zielarbeit
│   └── ist-ein → Ressourcenaktivierung
├── ist-ein → Intervention
│   ├── ist-ein → Fragetechnik
│   │   ├── ist-ein → Skalenfrage
│   │   └── ist-ein → Wunderfrage
│   └── ist-ein → Reflexion
└── ist-ein → Haltung
    ├── ist-ein → Ressourcenorientierung
    └── ist-ein → Allparteilichkeit

Abgrenzung zur Ontologie

• Die Ontologie definiert Klassen
• Die Taxonomie definiert deren Ordnung
• Eine Klasse existiert unabhängig von ihrer Position in der Taxonomie

Abgrenzung zur Semantik

• Taxonomie trägt keine Bedeutung im Aussagekontext
• Sie beantwortet keine Wahrheitsfragen
• Sie dient nicht der Interpretation einzelner Aussagen

Versionierung

• Änderungen an der Taxonomie sind versioniert
• Frühere Versionen bleiben referenzierbar
• Umbauten erfolgen durch Ergänzung, nicht durch stilles Überschreiben

Persistenz

• Taxonomische Beziehungen werden in der SQL-Datenbank gespeichert
• Jede Beziehung referenziert stabile Klassen-IDs
• Die Taxonomie ist Bestandteil des Graphmodells

Ergebnisartefakte

• Explizite Klassenhierarchie
• Versionierte taxonomische Beziehungen
• Navigierbare Ordnungsstruktur
• Chunk-Taxonomie-Mappings (neu)
• Entity-Taxonomie-Mappings (neu)

Prüfbedingungen für Supervision

• Keine taxonomische Beziehung existiert zwischen Entitäten
• Die Hierarchie ist zyklusfrei
• Jede Änderung ist versioniert und nachvollziehbar
• Alle Chunk-Mappings haben gültige Confidence-Werte (Contract TMC-001)
• Alle Entity-Mappings haben gültige Relevance-Werte (Contract TMC-003)

Provenienz und Nachvollziehbarkeit (Phase 10)

Ziel

Jede semantische Einheit ist vollständig rückverfolgbar. Provenienz stellt sicher, dass Wissen überprüfbar, korrigierbar und versionierbar bleibt. Ohne Provenienz gibt es keine belastbare semantische Infrastruktur.

Grundprinzip

• Keine Entität und keine Aussage existiert ohne Herkunft
• Herkunft ist strukturiert gespeichert, nicht implizit
• Provenienz ist Teil der semantischen Wahrheit

Provenienz von Entitäten

Jede Entität referenziert mindestens eine Quelle:

• Mehrere Quellen pro Entität sind zulässig
• Quellen werden nicht aggregiert oder verworfen

Provenienz von Aussagen

Jede Aussage referenziert ihre Entstehungsbasis:

• Die beteiligten Chunks
• Den Abschnittskontext
• Das zugrundeliegende Dokument

Aussagen ohne eindeutige Herkunft sind unzulässig.

Zeitliche Nachvollziehbarkeit

Für jede Entität und Aussage werden gespeichert:

Zeitangaben sind maschinenlesbar und vergleichbar.

Pipeline-Referenz

• Jede Persistenz speichert die verwendete Pipeline-Version
• Änderungen am Extraktions- oder Konsolidierungsprozess sind nachvollziehbar
• Reprocessing kann gezielt für einzelne Pipeline-Versionen erfolgen

Fehlerbehandlung und Korrektur

• Fehlerhafte Entitäten oder Aussagen können identifiziert werden
• Korrekturen erfolgen durch neue Versionen, nicht durch Überschreiben
• Alte Versionen bleiben referenzierbar
• Beziehungen zwischen Versionen sind explizit modelliert

Abgrenzung zu Annotationen

• Provenienz beschreibt Herkunft, nicht Bewertung
• Kommentare oder Bewertungen sind separate Konzepte

Persistenz

• Provenienzinformationen werden persistent gespeichert
• Provenienz ist Teil des Graphmodells und der SQL-Datenhaltung
• Kein Systemteil darf Provenienzinformationen verwerfen

Ergebnisartefakte

• Vollständige Quellenreferenzen für Entitäten
• Vollständige Quellenreferenzen für Aussagen
• Zeitlich und prozessual nachvollziehbarer Wissensbestand

Prüfbedingungen für Supervision

• Jede Entität und jede Aussage besitzt mindestens eine Quellenreferenz
• Jede Quellenreferenz verweist auf existierende Dokument-, Abschnitts- und Chunk-IDs
• Korrekturen sind über Versionsbeziehungen nachvollziehbar

Persistenz des Graphen (Phase 11)

Ziel

Der Graph wird als dauerhaftes, versioniertes Wissensmodell gespeichert. Er ist integraler Bestandteil der semantischen Wahrheit des Systems als Modell, wird aber aus der SQL-Quelle aufgebaut und als veröffentlichter Zustand persistiert.

Grundprinzip

• Der Graph bildet das semantische Rückgrat des Systems
• Er entsteht aus konsolidierten, validierten Daten vorheriger Phasen
• Er ist unabhängig von der konkreten Speichertechnologie
• Die SQL-Datenbank bleibt kanonisch - der Graph ist ein abgeleiteter, versionierter Veröffentlichungszustand

Inhalt des Graphen

Der Graph enthält ausschließlich persistente, geprüfte Elemente:

Temporäre Rohdaten sind im Graphen nicht enthalten.

Graphstruktur

• Entitäten sind Knoten
• Aussagen sind explizite semantische Beziehungseinheiten
• Relationen sind Bestandteil von Aussagen oder klar typisierte Kanten
• Ontologie und Taxonomie sind eigene Subgraphen mit stabiler Struktur

Konsistenz

Der Graph ist konsistent zu:

• Der SQL-Datenbank als Quelle der Wahrheit
• Den Versionen von Entitäten, Aussagen, Klassen und Beziehungen

Inkonsistenzen sind technisch ausgeschlossen oder explizit markiert.

Versionierung

• Änderungen erzeugen neue Versionen
• Alte Versionen bleiben referenzierbar
• Versionierung erfolgt semantisch, nicht nur technisch

Persistenzstrategie

Die Speicherung gewährleistet:

• Wiederherstellbarkeit - Graph kann aus SQL rekonstruiert werden
• Vergleichbarkeit - Versionen können verglichen werden
• Reproduzierbare Abfragen - Gleiche Abfrage, gleiches Ergebnis

Der Graph kann über mehrere physische Speicher verteilt sein, bleibt logisch konsistent.

Abgrenzung zur Vektordatenbank

Implementierungsoptionen

• Graphmodell in relationalen Tabellen (aktuell: MariaDB)
• Native Graphdatenbank (Neo4j, ArangoDB, TigerGraph)
• RDF Triplestore (Blazegraph, GraphDB)

Ergebnisartefakte

• Persistenter Wissensgraph als veröffentlichter Zustand
• Versionierte Graphzustände
• Konsistentes semantisches Modell

Prüfbedingungen für Supervision

• Jedes Graph-Element ist auf eine persistente Quelle zurückführbar
• Der Graph enthält keine Rohdaten oder temporären Elemente
• Änderungen am Graphen sind versioniert und nachvollziehbar
• Ein kompletter Neuaufbau aus SQL erzeugt denselben Graphzustand

Stabiler Zielzustand (Phase 12)

Ziel

Das System befindet sich in einem konsistenten, überprüfbaren und langfristig tragfähigen Zustand. Alle Systemkomponenten haben klar abgegrenzte Rollen. Semantische Wahrheit, Ähnlichkeit und Struktur sind strikt voneinander getrennt.

Systemrollen im Zielzustand

SQL-Datenbank: Single Source of Truth

Die SQL-Datenbank ist die kanonische Quelle für:

• Dokumente und Dokumentversionen
• Explizite Dokumentstruktur
• Chunks als textuelle Verarbeitungseinheiten
• Konsolidierte Entitäten
• Semantische Aussagen
• Ontologie-Klassen
• Taxonomische Beziehungen
• Provenienz und Versionierung

Kein anderes System besitzt semantische Autorität.

Vektordatenbank: Reiner Ähnlichkeitsindex

Graph: Strukturelles Wissensmodell

Der Graph repräsentiert:

• Entitäten und ihre Beziehungen
• Semantische Aussagen
• Ontologie und Taxonomie

Der Graph ist kein Nebenprodukt, sondern integraler Bestandteil der semantischen Infrastruktur. Er ist logisch konsistent mit der SQL-Datenbank.

Änderungsmanagement

• Jede Änderung erzeugt eine neue Version
• Änderungen erfolgen durch Ergänzung, nicht durch Überschreiben
• Alte Versionen bleiben referenzierbar
• Historische Zustände sind rekonstruierbar

Systemische Eigenschaften

Das System ist:

Semantische Fehler können lokalisiert, erklärt und behoben werden.

Zusammenfassung für Supervision

1. Ohne Graph existiert keine explizite Semantik
2. Ohne explizite Semantik entsteht kein überprüfbares Wissen
3. Vektoren liefern Nähe und Ähnlichkeit, nicht Bedeutung
4. Ontologie definiert Klassen, ersetzt aber keine Aussagen
5. Taxonomie ordnet Klassen, ersetzt aber keinen Kontext
6. Wahrheit ist strukturiert, versioniert und nachvollziehbar gespeichert, nicht generiert

Ergebnis des Gesamtprozesses

Eine stabile semantische Infrastruktur:

• Mit explizitem Bedeutungsmodell
• Mit klarer Trennung der Systemrollen
• Mit kontrollierter Evolution über Zeit

Prüfbedingungen für Supervision

• Für jede semantische Einheit existiert genau eine Quelle der Wahrheit
• Kein System überschreibt bedeutungstragende Daten eines anderen Systems
• Jeder Systemzustand ist versioniert und reproduzierbar