# ROADMAP_MATCHING.md **Version:** 1.0 **Status:** Living Document **Scope:** Architectural evolution of the Reconcilix matching framework --- # 1. Purpose Dieses Dokument beschreibt die geplante fachliche und architektonische Weiterentwicklung von Reconcilix. Es ist weder ein Releaseplan noch ein Engineering-Backlog. Stattdessen definiert die Roadmap den schrittweisen Ausbau der fachlichen Fähigkeiten (*Capabilities*) des Systems und dient als gemeinsame Orientierung für Architektur, Methodik und Engineering. Die Reihenfolge der beschriebenen Phasen stellt die angestrebte Entwicklung der Architektur dar. Einzelne Phasen können sich zeitlich überschneiden. --- # 2. Guiding Principles Die Weiterentwicklung von Reconcilix orientiert sich an folgenden Architekturprinzipien: - Interpretation before Reconciliation - Domain-driven Architecture - Controlled Vocabularies statt Hardcoding - Matching Strategies statt starrer Pipeline-Stages - Matching Techniques sind austauschbare Werkzeuge - Persist first, optimize later - Evolution durch Expertenevaluation - Trennung von Domain, Methodik, Persistenz und Engineering - External Services über klar definierte Systemgrenzen integrieren - Context is acquired incrementally. Die schrittweise Erweiterung verfügbarer Kontextinformationen erfolgt über klar definierte Architekturentscheidungen (ADR), ohne die Kopplung an einzelne Quellsysteme zu erhöhen. Diese Prinzipien besitzen Vorrang gegenüber einzelnen Implementierungsentscheidungen. --- # 3. Current Baseline ## Reference Architecture Die aktuelle Architektur basiert auf den folgenden Referenzdokumenten: - DM001 — Domain Model - DM002 — Persistence Model - ME001 — Interpretation Properties and Vocabulary Matching Patterns - ME002 — Interpretation-driven Reconciliation Diese Dokumente bilden gemeinsam die fachliche Referenzarchitektur von Reconcilix. --- ## Domain Model - SourceValue - ContextItem - InterpretationGraph - InterpretationNode - ReconciliationResult - CandidateItem - MatchDecision --- ## Methodology - InterpretationProperty - VocabularyMatchingPattern - Interpretation-driven Reconciliation --- ## Supported Entity Types Aktuell implementiert: - CONCEPT Weitere Entity Types sind Bestandteil späterer Phasen. --- ## Target Vocabulary Aktuell: - xTree / MCT --- ## Persistence **Production** - MySQL 8.0.46-0ubuntu0.24.04.3 **Local Development** - MariaDB 10.4.32 --- ## Client - OpenRefine --- # 4. Capability Roadmap ## Phase 1 — Interpretation-driven Core ### Ziel Integration der neuen Referenzarchitektur in die bestehende Reconcilix-Anwendung. ### Fähigkeiten - Integration von DM001 - Integration von DM002 - Umsetzung von ME001 - Umsetzung von ME002 - Persistenz sämtlicher Domain Objects - OpenRefine-Kompatibilität - Candidate Discovery gegen xTree/MCT - Übernahme des `SourceValue` aus OpenRefine - Vorbereitung der Architektur für die schrittweise Übernahme strukturierter Kontextinformationen ### Hinweis Die erste Implementierung übernimmt ausschließlich den `SourceValue` aus OpenRefine. Die Übernahme zusätzlicher `ContextItem`-Informationen wird in einem eigenen Architecture Decision Record (ADR) spezifiziert und anschließend schrittweise umgesetzt. --- ## Phase 2 — Context-aware Vector-assisted Reconciliation ### Ziel Kontextgestützte Candidate Discovery durch Integration eines externen API für vektorbasierte Suche. Reconcilix übernimmt weder die Vektorisierung des Vokabulars noch den Betrieb eines Vektorspeichers. Beide Aufgaben liegen außerhalb der Systemgrenze. ### Konzeptionelle Vorarbeiten - Definition der API-Spezifikation - Definition von Request und Response - Übergabe von `SourceValue` - Übergabe geeigneter `ContextItem`-Informationen (z. B. TEI-Kontext) - Definition der zurückgegebenen `CandidateItem` - Fehler- und Timeout-Verhalten - Versionierung - Reproduzierbarkeit ### Geplante Fähigkeiten - Integration eines externen Vector-Search-API - Mapping der API-Ergebnisse auf `CandidateItem` - Kombination klassischer Lookup-Verfahren mit Vector Search - Context-aware Candidate Ranking - Evaluation verschiedener embedding-basierter Verfahren ### Architekturgrenze Qdrant, Embedding-Modelle und GPU-Infrastruktur sind Bestandteile des externen Dienstes und nicht von Reconcilix. --- ## Phase 3 — GND Reconciliation via lobid-gnd ### Ziel Reconciliation von Sachbegriffen gegen die Gemeinsame Normdatei (GND). ### Fähigkeiten - Integration der lobid-gnd API - Candidate Discovery gegen die GND - Vergleich von MCT- und GND-Candidates - Evaluation der Matching Patterns - Nutzung vorhandener digiCULT-Erfahrungen ### Hinweis Phase 2 und Phase 3 können parallel entwickelt werden. --- ## Phase 4 — Multi-vocabulary Reconciliation ### Ziel Target-unabhängige Reconciliation gegen mehrere kontrollierte Vokabulare. ### Mögliche Target Systems - MCT - GND - Wikidata - Getty AAT - weitere Concept Schemes ### Fähigkeiten - Cross-Concept-Scheme Matching - Vergleich konkurrierender `CandidateItem` - gemeinsame Evaluation verschiedener Target Vocabularies --- ## Phase 5 — Adaptive Matching Strategies ### Ziel Adaptive Auswahl und Kombination verschiedener Matching Strategies. ### Fähigkeiten - Matching Plans - adaptive Strategy Selection - Kombination verschiedener Matching Techniques - automatische Eskalation zwischen - klassischem Lookup - Context Enrichment - Vector Search - Manual Review --- ## Phase 6 — Extended Domain Capabilities ### Weitere Entity Types - PERSON - PLACE - MULTIPLE ### Erweiterungen des Domain Models - mehrere InterpretationGraphs pro `SourceValue` - komplexere Interpretationsgraphen - konvergierende Graphpfade --- # 5. Deferred Features Bewusst zurückgestellt wurden: - Event Sourcing - Graph Database - vollständige Run-Historisierung - Replay kompletter Runs - Candidate-Spezialisierungen - komplexe Parent-Merges - automatische Vocabulary-Erzeugung --- # 6. Research Topics Mögliche Forschungs- und Evaluationsfelder: - automatische Interpretation - Confidence Calibration - Kombination symbolischer und vektorieller Verfahren - adaptive Strategy Selection - Evaluation verschiedener Embedding-Modelle - Explainable Reconciliation - Quality Metrics für Candidate Ranking --- # 7. Out of Scope Nicht Bestandteil der aktuellen Roadmap: - vollständige Ontologie-Reasoner - automatische Wissensmodellierung - generische KI-Agenten - Ersatz fachlicher Expertenentscheidungen durch LLMs LLMs und Embedding-Modelle werden ausschließlich als unterstützende Matching Techniques betrachtet. --- # 8. Implementation Priorities Die Integration der Architektur erfolgt in folgender Reihenfolge: ## Priority A — Domain Foundation - DM001 - DM002 - Persistenz - Integration in die bestehende Reconcilix-Anwendung --- ## Priority B — Methodology - InterpretationProperty - VocabularyMatchingPattern - Matching Strategy Selection - Interpretation Loop --- ## Priority C — External Services - xTree/MCT - OpenRefine - externes Vector-Search-API - lobid-gnd --- ## Priority D — Advanced Capabilities - Multi-vocabulary Matching - Adaptive Matching Strategies - weitere Entity Types --- # 9. Success Criteria ## Phase 1 Abgeschlossen, wenn - sämtliche Domain Objects implementiert sind, - DM001 und DM002 vollständig umgesetzt sind, - OpenRefine unverändert genutzt werden kann, - erste Expertenevaluationen möglich sind. --- ## Phase 2 Abgeschlossen, wenn - das externe Vector-Search-API spezifiziert und integriert ist, - Context-aware Candidate Discovery funktioniert, - Evaluation gegenüber klassischem Lookup durchgeführt wurde. --- ## Phase 3 Abgeschlossen, wenn - die lobid-gnd API integriert ist, - CandidateItems aus der GND verarbeitet werden, - ein Vergleich zwischen MCT- und GND-Reconciliation möglich ist. --- ## Phase 4–6 Gelten jeweils als abgeschlossen, wenn die neuen Fähigkeiten produktiv nutzbar sind und anhand realer Expertendaten evaluiert wurden. --- # 10. Living Document Diese Roadmap beschreibt die langfristige Entwicklung der fachlichen Fähigkeiten von Reconcilix. Sie wird regelmäßig anhand - neuer Architekturentscheidungen, - Engineering-Erkenntnisse, - Expertenevaluationen, - neuer Target Vocabularies, - wissenschaftlicher Erkenntnisse überprüft und fortgeschrieben. Neue Fähigkeiten werden nur aufgenommen, wenn sie mit den Guiding Principles vereinbar sind und einen nachweisbaren fachlichen Mehrwert bieten.