breakpilot-core/control-pipeline/INSTRUCTION-session-handover.md

Session-Uebergabe: Strukturelles Chunking + Qualitaetssicherung

Datum: 2026-05-02 Uebergeben von: Pipeline-Session (01.05 - 02.05.2026, ~20h)

Was wurde erledigt

Block	Was	Status
D2	RAG-Service speichert section/section_title/paragraph/page in Qdrant	✅
D3	Control Generator nutzt strukturelle Metadaten in source_citation	✅
D4	BGB § 312k Validierung — kritischen Overlap-Bug gefunden + gefixt	✅
D5	430/436 Dokumente re-ingestiert (alle 6 Collections)	✅
HTML-Fix	Stripping + Charset-Erkennung (ISO-8859-1), Opening-Block-Tags	✅
EUR-Lex	20 EU-Verordnungen als HTML ersetzt (DSGVO: 0%→92%)	✅
pdfplumber	Als PDF-Backend hinzugefuegt + PDF_EXTRACTION_BACKEND=auto	✅
NIST Regex	Nummerierte Abschnitte (1.1), Control-IDs (AC-1, PO.1)	✅
3 fehlende PDFs	EDPB Controller/Processor, GL 7, RTBF hochgeladen	✅
Frontend-Bug	requirements.map TypeError in Compliance Admin gefixt	✅
Qualitaetsreport	500 Controls geprueft: 13% OK, 41% Article-Mismatch	✅

Commits (breakpilot-core)

93099b2 feat(pipeline): structural metadata end-to-end (Blocks D2-D4)
ddad58f fix(rag): strip HTML tags before chunking + D5 re-ingestion scripts
a459636 fix(rag): HTML charset detection + opening block tag newlines
75dda9a feat(embedding): add pdfplumber backend for multi-column PDF extraction
41183ff fix(docker): set PDF_EXTRACTION_BACKEND to auto (was pymupdf)
5a6e588 docs: update session handover
3009f3d feat(embedding): add NIST/ENISA/standard section numbering to chunker

Aktuelle Qualitaet

Section-Rate nach Dateityp

Typ	Avg Section-Rate	Anmerkung
TXT (DE Gesetze)	79%	Exzellent
HTML (EUR-Lex + gesetze-im-internet)	56%	Gut (Praambeln haben keine Artikel)
PDF (EDPB/DSK Leitlinien)	60-98%	Gut
PDF (EU-Amtsblatt)	N/A	Durch EUR-Lex HTML ersetzt
PDF (NIST/BSI)	0-10%	Problematisch — siehe unten
TXT (OWASP)	0%	Eigenes Format, kein §/Artikel
Legal Templates (JSON/MD)	0%	Erwartet — keine juristische Struktur

Qualitaetsreport (500 Controls Stichprobe)

• 13% vollstaendig korrekt (Artikel gefunden, passt zum Chunk)
• 41% Article-nicht-im-Source-Text — Hauptursache: Controls aus alten kaputten PDF-Chunks generiert
• 7% kein Article in Citation
• 39% sonstige (Regulation gefunden aber Section-Matching-Issues)

Offene Probleme (Naechste Session)

1. NIST/ENISA/BSI PDFs (KRITISCH)

Problem: pypdf UND pdfplumber brechen den Text mehrspaliger Dokumente. Section-Nummern landen nicht am Zeilenanfang. Regex-Erweiterung hat nicht geholfen.

3 NIST PDFs waren kurzzeitig verloren (Chunks geloescht, Upload Timeout). Wiederherstellung aus MinIO wurde gestartet.

Loesung (priorisiert):

1. Text-Normalisierung nach PDF-Extraktion:

   def _normalize_multicolumn_text(text):
       # "1 . 1" → "1.1", "AC - 1" → "AC-1", "GV . OC - 01" → "GV.OC-01"
       text = re.sub(r'(\d+)\s*\.\s*(\d+)', r'\1.\2', text)
       text = re.sub(r'([A-Z]{2})\s*[-\.]\s*([A-Z]{2})\s*-\s*(\d+)', r'\1.\2-\3', text)
       text = re.sub(r'([A-Z]{2})\s*-\s*(\d+)', r'\1-\2', text)
       return text
   

2. Fehlende Regex-Patterns:

   • GV.OC-01 (NIST CSF 2.0): [A-Z]{2}\.[A-Z]{2}-\d{2}
   • A01:2021 (OWASP): A\d{2}(?::\d{4})?
   • AC-1(1) (NIST Enhancements): [A-Z]{2}-\d+\(\d+\)

3. Alternative: HTML von NIST/ENISA-Websites (wie EUR-Lex-Ansatz):

   • NIST: csrc.nist.gov bietet HTML-Versionen
   • ENISA: enisa.europa.eu bietet HTML-Versionen
   • Bester Ansatz fuer maximale Qualitaet

4. D5-Script fixen: Upload ZUERST, Delete NUR bei Erfolg (verhindert Datenverlust bei Timeout)

2. Citation-Backfill (WICHTIG)

Problem: 41% der Controls haben falsche Article-Citations (aus alten kaputten PDF-Chunks).

Loesung: Nachtraeglicher Abgleich:

1. Fuer jeden Control mit source_citation: Regulation in Qdrant suchen
2. Chunks mit passender Section finden
3. source_citation.article aktualisieren wenn besserer Match

Script: control-pipeline/scripts/quality_report.py existiert bereits als Basis.

3. Fehlende Gesetze (Block E3)

• BEG IV (Viertes Buerokratieentlastungsgesetz, 2024)
• Weitere aus project_missing_legal_sources.md

4. Frontend 500-Fehler

Das Compliance-Frontend (macmini:3007) zeigt noch 500-Fehler bei:

• /controls, /canonical, /control-instances, /findings, /vendors, /contracts

Der requirements.map TypeError ist gefixt, aber die API-500er deuten auf Backend-Probleme hin die separat untersucht werden muessen.

Kritische Dateien

Datei	Repo	Aenderung
embedding-service/main.py	core	Overlap-Fix, pdfplumber, NIST-Regex
rag-service/api/documents.py	core	D2 Payloads + HTML-Stripping
rag-service/html_utils.py	core	HTML-Strip + Charset (NEU)
rag-service/embedding_client.py	core	ChunkResult (D2)
control-pipeline/services/rag_client.py	core	page-Feld (D3)
control-pipeline/services/control_generator.py	core	section-Prio + page (D3)
control-pipeline/scripts/reingest_d5.py	core	Re-Ingestion Script
control-pipeline/scripts/replace_eu_pdfs_with_html.py	core	EUR-Lex Replacement
control-pipeline/scripts/quality_report.py	core	Qualitaetstest
docker-compose.yml	core	PDF_EXTRACTION_BACKEND=auto
canonical_control_service.py	compliance	_ensure_list Fix
ControlDetail.tsx	compliance	Array.isArray Guard

DB-Stand

Collection	Chunks	Dokumente
bp_compliance_ce	~23.600	~55
bp_compliance_gesetze	~32.000	~98
bp_compliance_datenschutz	~13.000	~107
bp_dsfa_corpus	~320	~20
bp_legal_templates	~1.460	~100
Gesamt	~70.000	~430

Tests

# Embedding-Service (58 Tests)
cd embedding-service && python3 -m pytest test_chunking.py test_d4_bgb.py -v

# RAG-Service (32 Tests)
cd rag-service && PYTHONPATH=. python3 -m pytest tests/ -v

# Control-Pipeline (387 Tests)
PYTHONPATH=control-pipeline python3 -m pytest control-pipeline/tests/ -v

# Qualitaetsreport (500 Controls)
python3 control-pipeline/scripts/quality_report.py --db-host macmini --sample 500

Empfohlene Reihenfolge naechste Session

1. NIST-Wiederherstellung pruefen (3 PDFs aus MinIO)
2. D5-Script fixen (Upload-before-Delete)
3. Text-Normalisierung fuer PDF-Extraktion
4. NIST/ENISA HTML-Downloads (wie EUR-Lex)
5. Citation-Backfill fuer bestehende Controls
6. Frontend 500-Fehler untersuchen
7. BEG IV + fehlende Gesetze ingestieren