Add README.md

README.md

@@ -0,0 +1,98 @@
+# Evidence Card Comparison
+
+## Überblick
+Dieses Repository dokumentiert und automatisiert den **Vergleich der Evidence Cards #40 und #42** hinsichtlich Performance und Validität. Das Experiment trägt die interne Kennung **evidence_card_comparison**.
+
+Ziel ist es, Metriken beider Karten objektiv zu analysieren, Gültigkeitsprüfungen durchzuführen und Audit-Ergebnisse festzuhalten.
+
+[Artikel zum Experiment](https://donau2space.de/tag-200-evidence-card-40-vs-42-und-warum-jetzt-pause-ist/)  
+[Git Repository](https://git.donau2space.de/Mika/evidence_card_comparison)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.
+
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko.  
+Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+---
+
+## Inhalt des Repositories
+Das Repository enthält drei Hauptartefakte:
+
+### 1. artifact.validation_checklist
+- **Art:** doc_only  
+- **Ziel:** mixed  
+- **Sprachen:** –  
+- **Zweck:** Dokumentation der Validitätschecks für Vergleichsexperimente der Evidence Cards.  
+- **Datentypen:**  
+  - *ValidationChecklist* (JSON): enthält Felder `checked_parameters`, `results`.
+
+### 2. artifact.metrics_analysis
+- **Art:** python_script  
+- **Ziel:** linux-userspace  
+- **Sprachen:** Python  
+- **Zweck:** Analyse und Visualisierung der Kernmetriken beider Evidence Cards.  
+- **API-Funktionen:**
+  - `analyze_metrics(card_data_40, card_data_42)` — führt die Analyse der beiden Datensätze durch.
+- **Datentypen:**
+  - *MetricResults* (JSON): Felder `retry_tail_p99`, `band_width`, `delta_band_width`.
+
+### 3. artifact.audit_report
+- **Art:** json_dataset  
+- **Ziel:** mixed  
+- **Sprachen:** JSON  
+- **Zweck:** Zusammenfassung der Ergebnisse des Mini-Audits der Preflight-Versuche.  
+- **Datentypen:**  
+  - *AuditResults* (JSON): Felder `acceptance_rate`, `attempts_to_success`, `failure_margin`.
+
+---
+
+## Installation & Nutzung
+### Voraussetzungen
+- Linux-Umgebung mit Python 3.8 oder höher.
+- Git und virtuelle Umgebung (optional).
+
+### Installation
+1. Repository klonen:
+   ```bash
+   git clone https://git.donau2space.de/Mika/evidence_card_comparison.git
+   cd evidence_card_comparison
+   ```
+2. Abhängigkeiten installieren:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Ausführung
+Das Hauptskript zur Metrikanalyse kann direkt ausgeführt werden:
+```bash
+python3 artifact.metrics_analysis.py --input40 data/card40.json --input42 data/card42.json --output metrics_results.json
+```
+
+---
+
+## Typische Use-Cases
+- Validitätsprüfung neuer Evidence Cards anhand definierter Checklisten.
+- Performancebewertung nach Metriken wie Bandbreite oder Retry-Latenz.
+- Statistische Audit-Auswertungen von Preflight-Versuchen.
+- Erstellung reproduzierbarer Vergleichsberichte.
+
+---
+
+## Struktur & mögliche Erweiterungen
+Die Repository-Struktur ist modular aufgebaut:
+- **/docs**: Dokumentation der Validierungsschritte.
+- **/analysis**: Python-Skripte für Metrikauswertung.
+- **/data**: JSON-Datensätze und Audit-Dateien.
+
+Mögliche Erweiterungen:
+- Integration weiterer Evidence-Card-Versionen.
+- Automatisierte Pipeline zur Vergleichsauswertung.
+- Visualisierung über Web-Dashboard.
+
+---
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+
+Die Inhalte wurden automatisiert durch KI erstellt. Nutzung ausschließlich auf eigene Verantwortung.