# ADR-A002 – Evaluation Export Pipeline


- Status: Proposed
- Datum erstellt: 2026-06-30
- Betrifft: Evaluation
- Implementiert in:
    - evaluation/matcult-the_vocnet_org_00000019/2026-06-30_E002_evaluation_export_pipeline/E002.md

---
# Ziel A002

Reconcilix stellt Evaluationen über einen wiederverwendbaren Exportdienst für Domainexpert:innen bereit.

# Kontext

Reconcilix wird iterativ anhand fachlicher Evaluationen weiterentwickelt.

Die Ergebnisse einer Reconciliation-Evaluation liegen derzeit als OpenRefine-Projekte vor. Diese enthalten insbesondere:

* `data.txt`
* `pool.txt`

Die interne Struktur dieser Dateien eignet sich gut für die technische Verarbeitung, ist jedoch für Domainexpert:innen nur eingeschränkt lesbar.
Die bisherige Auswertung erfolgt überwiegend manuell.
Für die fachliche Bewertung der Matching-Ergebnisse wird daher eine tabellarische Darstellung benötigt.

Diese soll

* nachvollziehbar,
* versionierbar,
* wiederholt erzeugbar
* und unabhängig von OpenRefine nutzbar sein.

---

# Entscheidung

Reconcilix erhält eine wiederverwendbare Exportlogik für OpenRefine-Projektexporte.

Darauf aufbauend wird eine einfache Weboberfläche zum Hochladen von Projektexporten bereitgestellt.

Die Oberfläche erzeugt daraus eine Evaluationstabelle für fachliche Rückmeldungen.
Die eigentliche Exportlogik wird in wiederverwendbare Service-Klassen ausgelagert.

Das Werkzeug liest OpenRefine-Exportdateien und erzeugt daraus eine tabellarische Auswertung.

Erstes Zielformat ist CSV.

Weitere Exportformate (z. B. ODS) können später ergänzt werden.



---

# Motivation

Die Entwicklung des Matching-Algorithmus soll datengetrieben erfolgen.

Dazu müssen Ergebnisse

* zwischen Versionen vergleichbar,
* durch Domainexpert:innen kommentierbar
* und langfristig reproduzierbar

sein.

Die Exporttabellen bilden die gemeinsame Arbeitsgrundlage zwischen Softwareentwicklung und Fachexpertise.

---

# Architektur

```text
OpenRefine Project

    Export .tar.gz


          │
          ▼


Weboberfläche Evaluation Export

          │
          ▼

Evaluation Export Service

          │
          ▼

CSV / später ODS

          │
          ▼

Domainexpert:innen

          │
          ▼

Feedback

          │
          ▼
          
 Reconcilix         
 
          │
          ▼

Neue Evaluation
```

---



# Architektonische Umsetzung

```text
public/
    evaluation-export.php

src/
    Evaluation/
        OpenRefineProjectReader.php
        OpenRefineProject.php
        EvaluationTableBuilder.php
        EvaluationRow.php
        EvaluationCandidate.php
        CsvEvaluationTableExporter.php

tools/
    exportOpenRefineEvaluationTable.php   optionaler CLI-Zugang

```


Die Weboberfläche ist der primäre Zugang für nicht-technische Nutzer:innen.
Die Exportlogik liegt in wiederverwendbaren Service-Klassen.
Ein CLI-Tool kann dieselbe Logik später ergänzend verwenden.

---

# Geplante CSV-Struktur

Mindestens:

* Source Value
* Match Status
* Matched Candidate
* Candidate URI
* Score
* Anzahl Kandidaten
* Kandidatenliste
* Kommentar
* Expertenentscheidung

Später optional:

* Evaluation (z.B. E022)
* Iteration  (z.B. I01) 
* Dataset
* Version
* verwendeter QueryTokenizer
* verwendete SearchStrategy
* verwendeter ReconciliationStore

---

# Konsequenzen

## Vorteile

* reproduzierbare Evaluationen
* bessere Zusammenarbeit mit Domainexpert:innen
* Versionierung der Evaluationen
* Vergleich zwischen Algorithmus-Versionen
* Grundlage für statistische Auswertungen

## Nachteile

* zusätzlicher Wartungsaufwand für das Exportwerkzeug

---

# Ausblick

Langfristig kann dieselbe Infrastruktur weitere Exportformate unterstützen, beispielsweise:

* ODS
* Excel
* HTML
* PDF

Ebenso können spätere Werkzeuge zwei Evaluationen direkt miteinander vergleichen und Änderungen automatisch hervorheben (Evaluation Diff).


# Nicht Bestandteil dieses ADR

- automatischer Vergleich zweier Evaluationen
- statistische Auswertungen
- webbasiertes Expertenfeedback
- Dashboard
 
Diese Themen können Bestandteil eines zukünftigen
**ADR-A0XY – Evaluation Pipeline**
werden.