Update Anwendung

src/answer_composer.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Optional, Tuple, Set
 
-from .llm_client_groq import ConversationMemory, is_meta_question
+from llm_client_groq import ConversationMemory, is_meta_question
 
 
 # ---------------------------------------------------------------------------
@@ -35,37 +35,208 @@ _ANSWER_REQUEST_PATTERNS = [
     re.compile(r"\bgib\s+mir\s+die\s+antwort\b", re.I),
 ]
 
+_SOURCE_MARKER_RE = re.compile(r"\[Quelle\s+(\d+)\]", re.I)
+_SOURCE_MARKER_MULTI_RE = re.compile(r"\[Quellen\s+([\d,\s]+)\]", re.I)
+_GRANULAR_BUCHSTABE_REF_RE = re.compile(
+    r"(§\s*\d{1,3}[a-z]?\s+Abs\.?\s*\d+[a-z]?)\s+"
+    r"(?:Buchst\.?|Buchstabe)\s*([a-z])",
+    re.I,
+)
+_DUPLICATE_PAREN_BASE_REF_RE = re.compile(
+    r"\((§\s*\d{1,3}[a-z]?\s+Abs\.?\s*\d+[a-z]?)(?:\s+(?:Buchst\.?|Buchstabe)\s*[a-z])\),\s*\1",
+    re.I,
+)
+_DUPLICATE_BASE_REF_RE = re.compile(
+    r"(§\s*\d{1,3}[a-z]?\s+Abs\.?\s*\d+[a-z]?)(?:\s+(?:Buchst\.?|Buchstabe)\s*[a-z]),\s*\1",
+    re.I,
+)
+_SECTION_REF_RE = re.compile(r"§\s*(\d{1,3}[a-z]?)(?!\d)", re.I)
+_TOKEN_RE = re.compile(r"[a-zäöüß0-9]{3,}", re.I)
+_STOPWORDS = {
+    "und", "oder", "der", "die", "das", "den", "dem", "des", "ein", "eine",
+    "einer", "einem", "einen", "für", "mit", "nach", "aus", "bei", "von",
+    "zur", "zum", "ist", "sind", "wird", "werden", "wann", "was", "wie",
+    "welche", "welcher", "welches", "apotheke", "rahmenvertrag", "vertrag",
+}
+
 _DOCUMENT_TASK_PROMPT = """
-Du beantwortest eine juristische Sachfrage ausschließlich anhand der bereitgestellten Textstellen.
-
-Verbindliche Regeln:
-- Verwende nur Informationen aus dem RAG-Kontext.
-- Erfinde keine Paragraphen, Anlagen, Fundstellen, Seiten, Begriffe oder Rechtsfolgen.
-- Wenn eine Aussage nicht aus den Textstellen belastbar folgt, sage das ausdrücklich.
-- Zitiere Quellen im Text nur mit den vorhandenen Markern wie [Quelle 1], [Quelle 2].
-- Verwende keine Quelle, die im RAG-Kontext nicht vorkommt.
-- Führe am Ende keine eigene lange Quellenliste auf, sofern die Anwendung separat Quellen ausgibt.
-- Bevorzuge spezifische Normstellen gegenüber allgemeinen oder nur semantisch ähnlichen Treffern.
-- Wenn die Frage ausdrücklich einen Paragraphen nennt, hat dieser Paragraph Vorrang.
-- Reine Nachbar-Chunks dienen nur dem Zusammenhang; stütze Kernaussagen primär auf direkt relevante Quellen.
-
-Juristische Arbeitsweise:
-- Prüfe Wortlaut, Systematik, Normzusammenhang und erkennbare Regelungsstruktur.
-- Wenn die Antwort nicht ausdrücklich im Wortlaut steht, aber aus mehreren Textstellen vertretbar ableitbar ist, formuliere dies als systematische Auslegung.
-- Unterscheide klar zwischen:
-  1. ausdrücklich geregelt,
-  2. systematisch/vertretbar ableitbar,
-  3. nicht belastbar aus den Textstellen ableitbar.
-- Sage nicht vorschnell „keine eindeutige Antwort“. Das ist nur zulässig, wenn weder Wortlaut noch Systematik noch Normzusammenhang eine tragfähige Antwort erlauben.
-
-Antwortschema:
-1. Kurzantwort
-2. Textgrundlage und Einordnung
-3. Subsumtion / systematische Auslegung
-4. Ausnahmen, Heilungen oder Retaxationsgrenzen, soweit relevant
-5. Ergebnisformel
-
-Bei Anspruchsfragen unterscheide besonders zwischen Anspruchstatbestand, ordnungsgemäßer bzw. vertragskonformer Leistungserbringung, Verstößen, Heilungsmöglichkeiten und Rechtsfolgen.
+Du bist ein juristischer Assistent.
+
+Beantworte ausschließlich anhand der bereitgestellten Textstellen.
+
+=========================
+EVIDENCE FIRST
+=========================
+
+Jede einzelne Aussage muss unmittelbar auf den bereitgestellten Quellen beruhen.
+
+Verwende niemals eigenes Wissen.
+
+Erfinde niemals
+
+- Paragraphen
+- Fundstellen
+- Definitionen
+- Rechtsfolgen
+- Ausnahmen
+- Beispiele
+- Vermutungen.
+
+Wenn sich eine Aussage nicht unmittelbar aus den Quellen ergibt,
+darf sie nicht ausgegeben werden.
+
+=========================
+LEGALDEFINITIONEN
+=========================
+
+Wenn nach der Bedeutung eines Begriffes gefragt wird:
+
+1. Suche zuerst nach einer Legaldefinition.
+
+2. Gib diese wortlautnah wieder.
+
+3. Erst danach darfst du eine kurze Einordnung geben.
+
+Eigene Definitionen sind unzulässig.
+
+=========================
+AUFZÄHLUNGEN
+=========================
+
+Wenn eine Norm
+
+- Voraussetzungen
+- Tatbestandsmerkmale
+- Fallgruppen
+- Alternativen
+- Kataloge
+
+enthält,
+
+müssen sämtliche Punkte vollständig wiedergegeben werden.
+
+Verwende niemals
+
+- unter anderem
+- beispielsweise
+- insbesondere
+
+wenn die Norm abschließend formuliert ist.
+
+=========================
+NICHT GEREGELT
+=========================
+
+Schreibe
+
+"nicht geregelt"
+
+nur wenn
+
+- keine einschlägige Quelle vorhanden ist
+
+UND
+
+- keine Legaldefinition vorhanden ist
+
+UND
+
+- keine andere bereitgestellte Norm die Frage beantwortet.
+
+=========================
+VORHANDENE PARAGRAPHEN NIEMALS LEUGNEN
+=========================
+
+Wenn eine bereitgestellte Textstelle den gefragten Paragraphen enthält
+(erkennbar am Feld "Abschnitt:" oder "Norm:" der Quelle, z. B. § 23),
+dann IST dieser Paragraph vorhanden.
+
+Sage in diesem Fall NIEMALS, der Paragraph sei
+- "nicht vorhanden"
+- "nicht enthalten"
+- "nicht in den bereitgestellten Quellen"
+- "nicht geregelt"
+
+und schreibe NIEMALS "es gibt keine Regelung/Aussage/Information zu diesem
+Paragraphen".
+
+Gib stattdessen wieder, was die Textstelle tatsächlich sagt — auch wenn sie kurz
+ist oder nur aus einer Verweisung besteht.
+
+=========================
+VERWEISUNGEN AUF EXTERNE NORMEN
+=========================
+
+Manche Paragraphen regeln einen Sachverhalt nicht selbst, sondern verweisen auf
+eine externe Norm (z. B. "Der Apothekenabschlag richtet sich nach § 130 SGB V").
+
+Wenn die bereitgestellte Textstelle nur auf eine externe Norm verweist:
+
+- Gib den Paragraphen und seine Verweisung wieder, mit dem Quellenmarker des
+  Paragraphen (z. B. "§ 23 bestimmt, dass sich der Apothekenabschlag nach
+  § 130 SGB V richtet [Quelle n]").
+- Weise darauf hin, dass die Einzelheiten in der verwiesenen Norm geregelt sind
+  und diese Norm nicht Teil der bereitgestellten Texte ist.
+
+Das ist eine gültige, vollständige Antwort und NICHT "nicht geregelt".
+
+=========================
+QUELLEN
+=========================
+
+Verwende ausschließlich vorhandene Marker.
+
+Jede tragende Aussage erhält mindestens einen Quellenmarker.
+
+Erfinde niemals Quellenmarker.
+
+Erfinde niemals Paragraphen.
+
+=========================
+ANTWORTSCHEMA
+=========================
+
+Gliedere die Antwort mit genau diesen Abschnitts-Überschriften.
+
+Jede Überschrift steht auf einer eigenen Zeile und endet mit einem Doppelpunkt.
+Der zugehörige Inhalt folgt in der nächsten Zeile.
+Zwischen den Abschnitten steht eine Leerzeile.
+
+Verwende reinen Text, KEIN Markdown:
+kein #, kein *, kein Fettdruck, keine Nummerierung der Überschriften.
+
+Kurzantwort:
+- Das Ergebnis in 1–3 Sätzen, mit Quellenmarker.
+
+Maßgebliche Norm:
+- Die einschlägige(n) Vorschrift(en), z. B. § 9 Abs. 3, mit Quellenmarker.
+
+Wortlaut / Kriterien:
+- Den maßgeblichen Normtext wortlautnah wiedergeben.
+- Aufzählungen (Buchstaben a–z, Nummern, Absätze) VOLLSTÄNDIG wiedergeben.
+
+Einordnung:
+- Nur, wenn zum Verständnis erforderlich und durch die Quellen gedeckt.
+- Andernfalls diesen Abschnitt inklusive Überschrift vollständig weglassen.
+
+Regeln zum Schema:
+
+- Abschnitte ohne Evidenz vollständig weglassen (inklusive Überschrift).
+- Keine Ergebnisformel, kein Fazit, keine Zusammenfassung am Ende.
+- Keine hypothetischen Ausnahmen.
+- Keine freien Schlussfolgerungen.
+
+=========================
+STIL
+=========================
+
+Präzise.
+
+Juristisch belastbar.
+
+Keine Wiederholungen.
+
+Keine Quellenliste am Ende.
 """.strip()
 
 
@@ -118,6 +289,9 @@ class AnswerComposer:
         include_neighbor_hits_in_context: bool = True,
         include_pure_neighbors_as_sources: bool = False,
         append_sources_to_answer: bool = False,
+        display_all_context_sources: bool = True,
+        validate_source_markers: bool = True,
+        prefer_direct_hits_over_neighbors: bool = True,
     ):
         self.llm = llm_client
         self.max_context_chars = max_context_chars
@@ -130,6 +304,9 @@ class AnswerComposer:
         self.include_neighbor_hits_in_context = include_neighbor_hits_in_context
         self.include_pure_neighbors_as_sources = include_pure_neighbors_as_sources
         self.append_sources_to_answer = append_sources_to_answer
+        self.display_all_context_sources = display_all_context_sources
+        self.validate_source_markers = validate_source_markers
+        self.prefer_direct_hits_over_neighbors = prefer_direct_hits_over_neighbors
 
     # ------------------------------------------------------------------
     # Meta-Hilfsmethoden
@@ -231,6 +408,37 @@ class AnswerComposer:
             return str(start)
         return "?"
 
+    @staticmethod
+    def _int_or_none(value: Any) -> Optional[int]:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    @classmethod
+    def _page_bounds(cls, hit: Dict[str, Any]) -> Tuple[Optional[int], Optional[int]]:
+        start = cls._int_or_none(cls._hit_value(hit, "page_start", default=None))
+        end = cls._int_or_none(cls._hit_value(hit, "page_end", default=None))
+        if end is None:
+            end = start
+        return start, end
+
+    @classmethod
+    def _highlight_text(cls, hit: Dict[str, Any], *, max_chars: int = 2000) -> str:
+        """Chunk-Text für die PDF-Fundstellen-Hervorhebung.
+
+        Die Ingest-Pipeline stellt jedem Chunk eine konstruierte Kontextzeile
+        wie "Vertrag · § 6 Titel" voran, die so nicht im PDF steht. Sie wird
+        entfernt, damit der Viewer nur echten Dokumenttext matchen muss.
+        """
+        text = cls._text(hit)
+        if not text:
+            return ""
+        head, sep, rest = text.partition("\n\n")
+        if sep and " · " in head and len(head) <= 200 and rest.strip():
+            text = rest.strip()
+        return text[:max_chars]
+
     @classmethod
     def _container(cls, hit: Dict[str, Any]) -> str:
         return str(cls._hit_value(hit, "container", "container_id", default="Unbekannt"))
@@ -243,6 +451,30 @@ class AnswerComposer:
     def _chunk_index(cls, hit: Dict[str, Any]) -> Any:
         return cls._hit_value(hit, "chunk_index", "chunk_index_in_section", default="?")
 
+    @classmethod
+    def _canonical_ref(cls, hit: Dict[str, Any]) -> str:
+        direct = cls._hit_value(hit, "canonical_ref", default="")
+        if direct:
+            return str(direct)
+
+        metadata = hit.get("metadata") or {}
+        paragraph = metadata.get("paragraph") or hit.get("paragraph") or cls._section(hit)
+        subsection = metadata.get("subsection") or hit.get("subsection")
+        sentence = metadata.get("sentence") or hit.get("sentence")
+        number = metadata.get("number") or hit.get("number")
+        letter = metadata.get("letter") or hit.get("letter")
+
+        parts: List[str] = [str(paragraph)] if paragraph else []
+        if subsection:
+            parts.append(f"Abs. {subsection}")
+        if sentence:
+            parts.append(f"Satz {sentence}")
+        if number:
+            parts.append(f"Nr. {number}")
+        if letter:
+            parts.append(f"Buchst. {str(letter).lower()}")
+        return " ".join(parts)
+
     @classmethod
     def _text(cls, hit: Dict[str, Any]) -> str:
         return str(hit.get("text") or hit.get("document") or "").strip()
@@ -261,6 +493,96 @@ class AnswerComposer:
         except (TypeError, ValueError):
             return 0.0
 
+    @classmethod
+    def _source_number(cls, hit: Dict[str, Any]) -> Optional[int]:
+        value = cls._hit_value(hit, "source_number", default=None)
+        try:
+            return int(value) if value is not None else None
+        except (TypeError, ValueError):
+            return None
+
+    @classmethod
+    def _is_pure_neighbor(cls, hit: Dict[str, Any]) -> bool:
+        kinds = set(cls._retrieval_kinds(hit))
+        return bool(kinds) and kinds == {"neighbor"}
+
+    @classmethod
+    def _is_direct_evidence(cls, hit: Dict[str, Any]) -> bool:
+        kinds = set(cls._retrieval_kinds(hit))
+        if not kinds:
+            return True
+        return not cls._is_pure_neighbor(hit)
+
+    @staticmethod
+    def _query_tokens(question: str) -> Set[str]:
+        tokens = {t.lower() for t in _TOKEN_RE.findall(question or "")}
+        return {t for t in tokens if t not in _STOPWORDS and not t.isdigit()}
+
+    @staticmethod
+    def _section_refs_from_question(question: str) -> Set[str]:
+        return {f"§ {m.group(1)}" for m in _SECTION_REF_RE.finditer(question or "")}
+
+    @classmethod
+    def _lexical_overlap(cls, question: str, hit: Dict[str, Any]) -> int:
+        query_terms = cls._query_tokens(question)
+        if not query_terms:
+            return 0
+        haystack = " ".join(
+            [
+                cls._canonical_ref(hit),
+                cls._section(hit),
+                cls._text(hit)[:2500],
+            ]
+        ).lower()
+        return sum(1 for term in query_terms if term in haystack)
+
+    @classmethod
+    def _specificity_score(cls, hit: Dict[str, Any]) -> int:
+        ref = cls._canonical_ref(hit).lower()
+        score = 0
+        if "abs." in ref or "absatz" in ref:
+            score += 2
+        if "satz" in ref:
+            score += 1
+        if "nr." in ref or "buchst." in ref:
+            score += 1
+        if cls._hit_value(hit, "unit_type", default="") == "definition":
+            score += 1
+        if cls._hit_value(hit, "chunk_kind", default="") == "parent":
+            score += 1
+        return score
+
+    def _hit_relevance_key(self, hit: Dict[str, Any], question: str = "") -> Tuple[Any, ...]:
+        kinds = set(self._retrieval_kinds(hit))
+        q_sections = self._section_refs_from_question(question)
+        section = self._section(hit)
+        canonical = self._canonical_ref(hit)
+
+        explicit = int(bool({"explicit_section", "section_lookup", "exact_reference", "definition_lookup"} & kinds))
+        direct = int(self._is_direct_evidence(hit)) if self.prefer_direct_hits_over_neighbors else 0
+        section_match = int(bool(q_sections and (section in q_sections or any(ref in canonical for ref in q_sections))))
+        definition = int(self._hit_value(hit, "unit_type", default="") == "definition")
+        specificity = self._specificity_score(hit)
+        overlap = self._lexical_overlap(question, hit)
+        pure_neighbor_penalty = -1 if self._is_pure_neighbor(hit) else 0
+        chunk_idx = self._chunk_index(hit)
+        try:
+            chunk_sort = -int(chunk_idx)
+        except (TypeError, ValueError):
+            chunk_sort = 0
+
+        return (
+            definition * 100,
+            explicit * 50,
+            section_match * 20,
+            direct * 10,
+            specificity * 5,
+            overlap,
+            self._score(hit),
+            pure_neighbor_penalty,
+            chunk_sort,
+        )
+
     @classmethod
     def _source_key(cls, hit: Dict[str, Any]) -> Tuple[Any, ...]:
         metadata = hit.get("metadata") or {}
@@ -308,44 +630,205 @@ class AnswerComposer:
 
         return True
 
-    def _prepare_hits_for_context(self, hits: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """Filtert, dedupliziert und begrenzt Treffer für den LLM-Kontext."""
+    def _prepare_hits_for_context(
+        self,
+        hits: List[Dict[str, Any]],
+        question: str = "",
+    ) -> List[Dict[str, Any]]:
+        """
+        Filtert, priorisiert und begrenzt Treffer für den LLM-Kontext.
+
+        Priorität:
+
+        1. Legaldefinitionen
+        2. explizite Paragraphentreffer
+        3. direkte Evidenz
+        4. Parent-Chunks
+        5. hohe Textübereinstimmung
+        6. Retrieval-Score
+        """
+
         if not hits:
             return []
 
-        filtered = [hit for hit in hits if self._should_keep_for_context(hit)]
+        filtered = [
+            hit
+            for hit in hits
+            if self._should_keep_for_context(hit)
+        ]
+
+        #
+        # Deduplizieren
+        #
+
+        deduped = {}
 
-        # Dedupe auf Chunk-Ebene.
-        deduped: Dict[Tuple[Any, ...], Dict[str, Any]] = {}
         for hit in filtered:
+
             key = self._source_key(hit)
-            old = deduped.get(key)
-            if old is None or self._score(hit) > self._score(old):
+
+            if (
+                key not in deduped
+                or self._score(hit) > self._score(deduped[key])
+            ):
                 deduped[key] = hit
 
         prepared = list(deduped.values())
 
-        # Begrenzung pro Section, damit eine lange Norm nicht den ganzen Kontext dominiert.
-        per_section_count: Dict[Tuple[str, str], int] = {}
-        section_limited: List[Dict[str, Any]] = []
+        #
+        # Priorisierung
+        #
+
+        # Paragraphen, die die Frage ausdrücklich nennt (z. B. "§ 23"), müssen
+        # zwingend an die Spitze des Kontexts. Sonst kann ein exakt passender,
+        # aber kurzer Chunk (etwa § 23 Apothekenabschlag) hinter semantisch
+        # ähnlichen Nachbarn landen, das LLM liest ihn nicht und behauptet
+        # fälschlich, der Paragraph sei "nicht geregelt/nicht vorhanden".
+        q_sections = self._section_refs_from_question(question)
+
+        def ranking(hit):
+
+            retrieval = set(self._retrieval_kinds(hit))
+
+            return (
+
+                #
+                # allerhöchste Priorität:
+                # exakt der in der Frage genannte Paragraph
+                #
+
+                bool(q_sections and self._section(hit) in q_sections),
+
+                #
+                # höchste Priorität
+                #
+
+                self._hit_value(hit, "unit_type", default="") == "definition",
+
+                #
+                # expliziter Paragraph
+                #
+
+                bool(
+                    {
+                        "explicit_section",
+                        "section_lookup",
+                        "definition_lookup",
+                        "exact_reference",
+                    }
+                    & retrieval
+                ),
+
+                #
+                # direkte Evidenz
+                #
+
+                self._is_direct_evidence(hit),
+
+                #
+                # Parent-Chunks bevorzugen
+                #
+
+                self._hit_value(
+                    hit,
+                    "chunk_kind",
+                    default="",
+                )
+                == "parent",
+
+                #
+                # spezifische Fundstelle
+                #
+
+                self._specificity_score(hit),
+
+                #
+                # lexikalische Übereinstimmung
+                #
+
+                self._lexical_overlap(
+                    question,
+                    hit,
+                ),
+
+                #
+                # Retrievalscore
+                #
+
+                self._score(hit),
+
+                #
+                # Neighbor zuletzt
+                #
+
+                not self._is_pure_neighbor(hit),
+
+            )
 
         prepared.sort(
-            key=lambda h: (
-                1 if "explicit_section" in set(self._retrieval_kinds(h)) else 0,
-                self._score(h),
-                -int(self._chunk_index(h) if str(self._chunk_index(h)).isdigit() else 0),
-            ),
+            key=ranking,
             reverse=True,
         )
 
+        #
+        # Maximal x Chunks pro Paragraph
+        #
+
+        section_limited = []
+
+        per_section_count = {}
+
         for hit in prepared:
-            section_key = (self._container(hit), self._section(hit))
-            count = per_section_count.get(section_key, 0)
-            if count >= self.max_chunks_per_section:
+
+            key = (
+                self._container(hit),
+                self._section(hit),
+            )
+
+            if (
+                per_section_count.get(key, 0)
+                >= self.max_chunks_per_section
+            ):
                 continue
-            per_section_count[section_key] = count + 1
+
+            per_section_count[key] = (
+                per_section_count.get(key, 0)
+                + 1
+            )
+
             section_limited.append(hit)
 
+        #
+        # Sicherstellen,
+        # dass mindestens eine Definition enthalten bleibt
+        #
+
+        definitions = [
+            h
+            for h in prepared
+            if self._hit_value(
+                h,
+                "unit_type",
+                default="",
+            )
+            == "definition"
+        ]
+
+        if definitions:
+
+            first_definition = definitions[0]
+
+            if first_definition not in section_limited:
+
+                section_limited.insert(
+                    0,
+                    first_definition,
+                )
+
+        #
+        # Kontext begrenzen
+        #
+
         return section_limited[: self.max_hits_for_context]
 
     @classmethod
@@ -356,28 +839,34 @@ class AnswerComposer:
         max_sources: int = 5,
         include_pure_neighbors: bool = False,
         allowed_container_ids: Optional[List[str]] = None,
+        referenced_source_numbers: Optional[Set[int]] = None,
     ) -> List[Dict[str, Any]]:
         """
-        Baut eine deduplizierte Quellenliste für die Anzeige.
+        Baut eine kuratierte, nummern-stabile Quellenliste für die Anzeige.
 
         Wichtig:
-        - Nicht alle Retrieval-Treffer sind Quellen.
-        - Reine Neighbor-Treffer werden standardmäßig nicht angezeigt.
-        - Mehrere Chunks derselben Section/Seiten werden zusammengefasst.
+        - Quellenmarker aus dem RAG-Kontext bleiben stabil erhalten.
+        - Mehrere Chunks derselben Section/Seiten werden gruppiert, aber die
+          zugehörigen [Quelle n]-Nummern bleiben sichtbar.
+        - Reine Neighbor-Treffer werden standardmäßig nicht als Quellen angezeigt.
         """
         allowed = set(allowed_container_ids or [])
-        seen: Set[Tuple[Any, Any, Any]] = set()
-        sources: List[Dict[str, Any]] = []
+        grouped: Dict[Tuple[Any, Any, Any], Dict[str, Any]] = {}
 
-        sorted_hits = sorted(hits, key=cls._score, reverse=True)
+        def order_key(hit: Dict[str, Any]) -> Tuple[int, float]:
+            number = cls._source_number(hit)
+            if number is not None:
+                return (number, 0.0)
+            return (10_000, -cls._score(hit))
 
-        for hit in sorted_hits:
+        for hit in sorted(hits, key=order_key):
             container = cls._container(hit)
             if allowed and container not in allowed:
                 continue
 
-            kinds = set(cls._retrieval_kinds(hit))
-            if kinds == {"neighbor"} and not include_pure_neighbors:
+            number = cls._source_number(hit)
+            is_referenced = bool(referenced_source_numbers and number in referenced_source_numbers)
+            if cls._is_pure_neighbor(hit) and not include_pure_neighbors and not is_referenced:
                 continue
 
             text = cls._text(hit)
@@ -385,27 +874,118 @@ class AnswerComposer:
                 continue
 
             key = cls._source_display_key(hit)
-            if key in seen:
-                continue
-            seen.add(key)
+            number = cls._source_number(hit)
+            canonical = cls._canonical_ref(hit)
+            kinds = cls._retrieval_kinds(hit)
+
+            # PDF-Locator: Datei, numerische Seiten und Hervorhebungstext pro
+            # Chunk, damit die UI die Fundstelle im PDF ansteuern kann.
+            page_start, page_end = cls._page_bounds(hit)
+            source_file = str(cls._hit_value(hit, "source_file", default="") or "")
+            doc_id = str(cls._hit_value(hit, "doc_id", default="") or "")
+            highlight = cls._highlight_text(hit)
+            highlight_entry = (
+                {"page_start": page_start, "page_end": page_end, "text": highlight}
+                if highlight
+                else None
+            )
 
-            sources.append(
-                {
-                    "source_number": cls._hit_value(hit, "source_number", default=None),
+            item = grouped.get(key)
+            if item is None:
+                grouped[key] = {
+                    "source_number": number,
+                    "source_numbers": [number] if number is not None else [],
+                    "source_marker": f"[Quelle {number}]" if number is not None else "",
+                    "source_label": f"[Quelle {number}]" if number is not None else "",
                     "container": container,
                     "section": cls._section(hit),
+                    "canonical_ref": canonical,
+                    "canonical_refs": [canonical] if canonical else [],
                     "page_range": cls._page_range(hit),
+                    "page_start": page_start,
+                    "page_end": page_end,
+                    "source_file": source_file,
+                    "doc_id": doc_id,
+                    "highlights": [highlight_entry] if highlight_entry else [],
                     "path": cls._hit_value(hit, "path", "section_path", default=""),
                     "score": round(cls._score(hit), 4),
-                    "retrieval_kinds": cls._retrieval_kinds(hit),
+                    "retrieval_kinds": list(dict.fromkeys(kinds)),
                     "chunk_index": cls._chunk_index(hit),
+                    "display_title": "",
+                    "display_label": "",
                 }
-            )
+                continue
 
-            if len(sources) >= max_sources:
-                break
+            if page_start is not None and (item.get("page_start") is None or page_start < item["page_start"]):
+                item["page_start"] = page_start
+            if page_end is not None and (item.get("page_end") is None or page_end > item["page_end"]):
+                item["page_end"] = page_end
+            if source_file and not item.get("source_file"):
+                item["source_file"] = source_file
+            if doc_id and not item.get("doc_id"):
+                item["doc_id"] = doc_id
+            if highlight_entry is not None:
+                existing_texts = {(h.get("text") or "")[:120] for h in item.get("highlights") or []}
+                if highlight[:120] not in existing_texts:
+                    item.setdefault("highlights", []).append(highlight_entry)
+
+            if number is not None and number not in item["source_numbers"]:
+                item["source_numbers"].append(number)
+                item["source_numbers"].sort()
+                item["source_number"] = item["source_numbers"][0]
+                if len(item["source_numbers"]) == 1:
+                    item["source_marker"] = f"[Quelle {item['source_numbers'][0]}]"
+                    item["source_label"] = item["source_marker"]
+                else:
+                    joined = ", ".join(str(n) for n in item["source_numbers"])
+                    item["source_marker"] = f"[Quellen {joined}]"
+                    item["source_label"] = item["source_marker"]
+
+            if canonical and canonical not in item["canonical_refs"]:
+                item["canonical_refs"].append(canonical)
+                # Behalte als Hauptfundstelle die spezifischste Referenz.
+                item["canonical_ref"] = max(item["canonical_refs"], key=lambda r: ("Abs." in r, "Satz" in r, len(r)))
+
+            item["score"] = max(float(item.get("score", 0.0)), round(cls._score(hit), 4))
+            for kind in kinds:
+                if kind not in item["retrieval_kinds"]:
+                    item["retrieval_kinds"].append(kind)
+
+        sources = list(grouped.values())
 
-        return sources
+        for source in sources:
+            numbers = source.get("source_numbers") or []
+            if numbers:
+                if len(numbers) == 1:
+                    label = f"[Quelle {numbers[0]}]"
+                else:
+                    label = "[Quellen " + ", ".join(str(n) for n in numbers) + "]"
+            else:
+                label = ""
+            source["source_marker"] = label
+            source["source_label"] = label
+            canonical_refs = source.get("canonical_refs") or []
+            canonical = "; ".join(canonical_refs[:3]) if canonical_refs else source.get("canonical_ref")
+            if canonical and canonical != source.get("section"):
+                source["display_title"] = f"{label} {source.get('container')}::{source.get('section')} ({canonical}), Seiten {source.get('page_range')}".strip()
+            else:
+                source["display_title"] = f"{label} {source.get('container')}::{source.get('section')}, Seiten {source.get('page_range')}".strip()
+            source["display_label"] = source["display_title"]
+
+        sources.sort(key=lambda s: (s.get("source_numbers") or [10_000])[0])
+
+        referenced = set(referenced_source_numbers or set())
+        if referenced:
+            referenced_sources = [
+                s for s in sources
+                if referenced.intersection(set(s.get("source_numbers") or []))
+            ]
+            other_sources = [s for s in sources if s not in referenced_sources]
+            # Never drop sources that are cited in the answer.  The cap only limits extras.
+            budget = max(int(max_sources), len(referenced_sources))
+            return (referenced_sources + other_sources[: max(0, budget - len(referenced_sources))])
+
+        return sources[:max_sources]
 
     @staticmethod
     def format_sources_markdown(sources: List[Dict[str, Any]]) -> str:
@@ -416,8 +996,29 @@ class AnswerComposer:
         for source in sources:
             container = source.get("container", "Unbekannt")
             section = source.get("section", "ohne Abschnitt")
+            canonical_refs = source.get("canonical_refs") or []
+            canonical = "; ".join(canonical_refs[:3]) if canonical_refs else source.get("canonical_ref")
             pages = source.get("page_range", "?")
-            lines.append(f"- {container}::{section}, Seiten {pages}")
+            marker = source.get("source_marker") or source.get("source_label") or ""
+            if not marker:
+                numbers = source.get("source_numbers") or []
+                if numbers:
+                    if len(numbers) == 1:
+                        marker = f"[Quelle {numbers[0]}]"
+                    else:
+                        marker = "[Quellen " + ", ".join(str(n) for n in numbers) + "]"
+                else:
+                    marker = "-"
+
+            role = ""
+            kinds = set(source.get("retrieval_kinds") or [])
+            if kinds == {"neighbor"}:
+                role = " · Kontext/Nachbar"
+
+            if canonical and canonical != section:
+                lines.append(f"- {marker} {container}::{section} ({canonical}), Seiten {pages}{role}")
+            else:
+                lines.append(f"- {marker} {container}::{section}, Seiten {pages}{role}")
         return "\n".join(lines)
 
     # ------------------------------------------------------------------
@@ -430,33 +1031,60 @@ class AnswerComposer:
         section = cls._section(hit)
         page_range = cls._page_range(hit)
         chunk_index = cls._chunk_index(hit)
-        kinds = cls._retrieval_kinds(hit)
-        kind_text = ",".join(kinds) if kinds else "retrieved"
+
         score = cls._score(hit)
         text = cls._text(hit)
 
+        canonical_ref = cls._canonical_ref(hit)
+
+        role = (
+            "Kontext/Nachbar"
+            if cls._is_pure_neighbor(hit)
+            else "Hauptquelle"
+        )
+
+        retrieval = ", ".join(cls._retrieval_kinds(hit)) or "retrieved"
+
+        unit_type = cls._hit_value(hit, "unit_type", default="")
+
+        chunk_kind = cls._hit_value(hit, "chunk_kind", default="")
+
         return (
-            f"[Quelle {index}] {container}::{section} "
-            f"(Seiten {page_range}, Chunk {chunk_index}, Typ {kind_text}, Score {score:.4f})\n"
+            f"[Quelle {index}]\n"
+            f"Container: {container}\n"
+            f"Abschnitt: {section}\n"
+            f"Norm: {canonical_ref}\n"
+            f"Typ: {unit_type or '-'}\n"
+            f"Chunk: {chunk_kind or '-'}\n"
+            f"Rolle: {role}\n"
+            f"Retrieval: {retrieval}\n"
+            f"Seiten: {page_range}\n"
+            f"Chunk-Index: {chunk_index}\n"
+            f"Score: {score:.4f}\n"
+            f"\n"
+            f"Text:\n"
             f"{text}"
         )
 
-    def _build_rag_context(self, hits: List[Dict[str, Any]]) -> Tuple[str, List[Dict[str, Any]]]:
-        prepared_hits = self._prepare_hits_for_context(hits)
+    def _build_rag_context(self, hits: List[Dict[str, Any]], question: str = "") -> Tuple[str, List[Dict[str, Any]]]:
+        prepared_hits = self._prepare_hits_for_context(hits, question=question)
         if not prepared_hits:
             return "", []
 
         parts: List[str] = []
         total = 0
 
+        used_hits: List[Dict[str, Any]] = []
         for i, hit in enumerate(prepared_hits, start=1):
-            block = self._format_source_block(i, hit)
+            hit_with_number = dict(hit)
+            hit_with_number["source_number"] = i
+            block = self._format_source_block(i, hit_with_number)
             if self.max_context_chars and total + len(block) + 2 > self.max_context_chars:
                 break
             parts.append(block)
+            used_hits.append(hit_with_number)
             total += len(block) + 2
 
-        used_hits = prepared_hits[: len(parts)]
         return "\n\n".join(parts), used_hits
 
     @staticmethod
@@ -502,11 +1130,256 @@ class AnswerComposer:
         # Entfernt nur einen finalen Abschnitt "Quellen:" oder "Fundstellen:",
         # nicht aber Quellenmarker im Fließtext wie [Quelle 1].
         pattern = re.compile(
-            r"\n{1,3}(Quellen|Fundstellen)\s*:\s*\n(?:.|\n)*$",
+            r"(?:\n{1,3}|(?<=\.)\s+|^)(Quellen|Fundstellen)\s*:\s*(?:\n|.)*$",
             flags=re.I,
         )
         return pattern.sub("", text).strip()
 
+    @staticmethod
+    def _used_source_numbers(used_hits: List[Dict[str, Any]]) -> Set[int]:
+        numbers: Set[int] = set()
+        for hit in used_hits:
+            value = hit.get("source_number")
+            try:
+                if value is not None:
+                    numbers.add(int(value))
+            except (TypeError, ValueError):
+                continue
+        return numbers
+
+    @staticmethod
+    def _legal_ref_norm(text: str) -> str:
+        """Normalize legal references for conservative support checks."""
+        s = (text or "").lower()
+        s = s.replace("§§", "§")
+        s = re.sub(r"\babsatz\b", "abs", s)
+        s = re.sub(r"\babs\.\b", "abs", s)
+        s = re.sub(r"\bbuchstabe\b", "buchst", s)
+        s = re.sub(r"\bbuchst\.\b", "buchst", s)
+        s = re.sub(r"\s+", " ", s)
+        return s.strip(" .,:;()[]")
+
+    @classmethod
+    def _supported_legal_ref_blobs(cls, used_hits: List[Dict[str, Any]]) -> Set[str]:
+        """Build normalized blobs used to decide whether a granular ref is grounded."""
+        blobs: Set[str] = set()
+        for hit in used_hits:
+            bits = [
+                cls._canonical_ref(hit),
+                cls._section(hit),
+                str(cls._hit_value(hit, "paragraph", default="")),
+                str(cls._hit_value(hit, "subsection", default="")),
+                str(cls._hit_value(hit, "letter", default="")),
+                cls._text(hit)[:3000],
+            ]
+            blob = cls._legal_ref_norm(" ".join(bits))
+            if blob:
+                blobs.add(blob)
+        return blobs
+
+    @classmethod
+    def _strip_unsupported_granular_refs(cls, answer: str, used_hits: List[Dict[str, Any]]) -> str:
+        """Remove unsupported Buchst.-precision while preserving supported paragraph/Abs. refs.
+
+        This is intentionally conservative. It does not delete the base norm; it only
+        downgrades e.g. "§ 6 Abs. 1 Buchst. a" to "§ 6 Abs. 1" when that granular
+        letter reference is not present in any canonical ref or source text.
+        """
+        text = answer or ""
+        if not text:
+            return text
+
+        # First fix common self-contradictory patterns produced by LLMs.
+        text = _DUPLICATE_PAREN_BASE_REF_RE.sub(r"(\1)", text)
+        text = _DUPLICATE_BASE_REF_RE.sub(r"\1", text)
+        supported_blobs = cls._supported_legal_ref_blobs(used_hits)
+
+        def is_supported(full: str, base: str, letter: str) -> bool:
+            full_norm = cls._legal_ref_norm(full)
+            # Support exact canonical/textual occurrences, including variants.
+            variants = {
+                full_norm,
+                cls._legal_ref_norm(f"{base} Buchst. {letter}"),
+                cls._legal_ref_norm(f"{base} Buchstabe {letter}"),
+                cls._legal_ref_norm(f"{base} {letter})"),
+            }
+            return any(any(v and v in blob for blob in supported_blobs) for v in variants)
+
+        def repl(match: re.Match[str]) -> str:
+            full = match.group(0)
+            base = re.sub(r"\s+", " ", match.group(1)).strip()
+            letter = match.group(2).lower()
+            return full if is_supported(full, base, letter) else base
+
+        text = _GRANULAR_BUCHSTABE_REF_RE.sub(repl, text)
+        text = re.sub(r"\(\s*(§\s*\d{1,3}[a-z]?\s+Abs\.?\s*\d+[a-z]?)\s*\),\s*\1", r"(\1)", text, flags=re.I)
+        return text
+
+    @classmethod
+    def _referenced_source_numbers(cls, answer: str) -> Set[int]:
+        numbers: Set[int] = set()
+        for m in _SOURCE_MARKER_RE.finditer(answer or ""):
+            try:
+                numbers.add(int(m.group(1)))
+            except (TypeError, ValueError):
+                pass
+        for m in _SOURCE_MARKER_MULTI_RE.finditer(answer or ""):
+            for part in re.split(r"[,\s]+", m.group(1)):
+                if not part:
+                    continue
+                try:
+                    numbers.add(int(part))
+                except (TypeError, ValueError):
+                    pass
+        return numbers
+
+    @classmethod
+    def _postprocess_document_answer(
+        cls,
+        answer: str,
+        used_hits: List[Dict[str, Any]],
+        *,
+        validate_markers: bool = True,
+    ) -> str:
+        """
+        Bereitet die LLM-Antwort nach.
+
+        Schritte:
+        1. Entfernt frei erzeugte Quellenlisten.
+        2. Entfernt ungültige Quellenmarker.
+        3. Entfernt nicht belegte Buchstaben-/Untergliederungsreferenzen.
+        4. Entfernt typische Halluzinationsformulierungen.
+        5. Bereinigt Formatierung.
+        """
+
+        text = cls._strip_model_generated_sources(answer)
+
+        if validate_markers:
+            text = cls._strip_invalid_source_markers(text, used_hits)
+
+        text = cls._strip_unsupported_granular_refs(text, used_hits)
+
+        # -------------------------------------------------------------
+        # Halluzinationsschutz
+        # -------------------------------------------------------------
+
+        hallucination_patterns = [
+
+            # erfundene Ergebnisblöcke
+            r"(?im)^Ergebnis:\s*",
+
+            # pauschale Aussagen
+            r"(?im)^Es bestehen keine Ausnahmen\.?\s*$",
+            r"(?im)^Es sind keine Ausnahmen geregelt\.?\s*$",
+            r"(?im)^Weitere Ausnahmen sind nicht vorgesehen\.?\s*$",
+
+            # spekulative Aussagen
+            r"(?im)^Im Einzelfall kann.*$",
+            r"(?im)^Die Krankenkasse kann im Einzelfall.*$",
+
+            # unbelegte Schlussformeln
+            r"(?im)^Zusammenfassend gilt.*$",
+        ]
+
+        for pattern in hallucination_patterns:
+            text = re.sub(pattern, "", text)
+
+        # -------------------------------------------------------------
+        # Leere Überschriften entfernen
+        #
+        # Wichtig: Nur *tatsächlich* leere Abschnitts-Überschriften entfernen.
+        # Eine Überschrift mit Inhalt in der Folgezeile (z. B. "Einordnung:\n
+        # Die Kriterien sind abschließend.") muss erhalten bleiben. Die frühere
+        # Regex `^Einordnung:\s*$` hätte auch das Label mit Inhalt entfernt, weil
+        # `$` im MULTILINE-Modus bereits vor dem Zeilenumbruch greift.
+        # -------------------------------------------------------------
+
+        text = cls._strip_empty_section_headings(text)
+
+        # -------------------------------------------------------------
+        # Leerraum bereinigen
+        # -------------------------------------------------------------
+
+        text = re.sub(r"[ \t]{2,}", " ", text)
+
+        text = re.sub(r"\n{3,}", "\n\n", text)
+
+        text = text.strip()
+
+        return text
+
+    # Abschnitts-Überschriften, die als leere Reste entfernt werden dürfen.
+    # Enthält die Labels des aktuellen Schemas sowie Alt-Reste.
+    _SECTION_HEADINGS = (
+        "Kurzantwort",
+        "Maßgebliche Norm",
+        "Maßgebliche Norm(en)",
+        "Wortlaut / Kriterien",
+        "Wortlaut",
+        "Einordnung",
+        "Ausnahmen",
+        "Ergebnis",
+        "Heilungen",
+        "Retaxationsgrenzen",
+    )
+
+    @classmethod
+    def _strip_empty_section_headings(cls, text: str) -> str:
+        """Entfernt Abschnitts-Überschriften, denen kein Inhalt folgt.
+
+        Eine Überschrift gilt als leer, wenn bis zur nächsten Überschrift oder
+        bis zum Textende keine inhaltliche Zeile folgt. Überschriften mit Inhalt
+        bleiben unangetastet.
+        """
+        if not text:
+            return text
+
+        label_re = re.compile(
+            r"^(?:#+\s*)?(?:"
+            + "|".join(re.escape(h) for h in cls._SECTION_HEADINGS)
+            + r"):?\s*$",
+            re.I,
+        )
+
+        lines = text.split("\n")
+        keep = [True] * len(lines)
+
+        for i, line in enumerate(lines):
+            if not label_re.match(line.strip()):
+                continue
+
+            # Nächste nicht-leere Zeile suchen.
+            j = i + 1
+            while j < len(lines) and not lines[j].strip():
+                j += 1
+
+            # Leer, wenn Textende erreicht ist oder direkt die nächste
+            # Überschrift folgt.
+            if j >= len(lines) or label_re.match(lines[j].strip()):
+                keep[i] = False
+
+        return "\n".join(line for idx, line in enumerate(lines) if keep[idx])
+
+    @classmethod
+    def _strip_invalid_source_markers(cls, answer: str, used_hits: List[Dict[str, Any]]) -> str:
+        """Entfernt Marker wie [Quelle 9], wenn Quelle 9 nicht im Kontext stand."""
+        valid_numbers = cls._used_source_numbers(used_hits)
+        if not valid_numbers:
+            return _SOURCE_MARKER_RE.sub("", answer or "").strip()
+
+        def repl(match: re.Match[str]) -> str:
+            try:
+                number = int(match.group(1))
+            except (TypeError, ValueError):
+                return ""
+            return match.group(0) if number in valid_numbers else ""
+
+        cleaned = _SOURCE_MARKER_RE.sub(repl, answer or "")
+        # Nur überflüssige Leerzeichen vor Satzzeichen bereinigen; Zeilenumbrüche und Schema bleiben erhalten.
+        cleaned = re.sub(r"[ 	]{2,}", " ", cleaned)
+        cleaned = re.sub(r"\s+([,.;:])", r"\1", cleaned)
+        return cleaned.strip()
+
     # ------------------------------------------------------------------
     # Öffentliche API
     # ------------------------------------------------------------------
@@ -538,7 +1411,7 @@ class AnswerComposer:
                 "none",
             )
 
-        rag_context, used_hits = self._build_rag_context(hits)
+        rag_context, used_hits = self._build_rag_context(hits, question=question)
         if not rag_context.strip():
             return (
                 "Die gefundenen Treffer enthalten keinen verwertbaren Text. "
@@ -551,14 +1424,16 @@ class AnswerComposer:
             rag_context=rag_context,
             memory=memory,
         )
-        answer = self._strip_model_generated_sources(answer)
+        answer = self._postprocess_document_answer(answer, used_hits, validate_markers=self.validate_source_markers)
+        referenced_numbers = self._referenced_source_numbers(answer)
 
         if self.append_sources_to_answer:
             sources = self.build_sources(
                 used_hits,
-                max_sources=self.max_sources,
-                include_pure_neighbors=self.include_pure_neighbors_as_sources,
+                max_sources=(len(used_hits) if self.display_all_context_sources else self.max_sources),
+                include_pure_neighbors=(self.include_pure_neighbors_as_sources or self.display_all_context_sources),
                 allowed_container_ids=list(self.allowed_container_ids) if self.allowed_container_ids else None,
+                referenced_source_numbers=referenced_numbers,
             )
             sources_md = self.format_sources_markdown(sources)
             if sources_md:
@@ -579,7 +1454,7 @@ class AnswerComposer:
             answer, source_type = self._answer_meta(question, memory)
             return answer, source_type, []
 
-        rag_context, used_hits = self._build_rag_context(hits)
+        rag_context, used_hits = self._build_rag_context(hits, question=question)
         if not rag_context.strip():
             return (
                 "Die gefundenen Treffer enthalten keinen verwertbaren Text. "
@@ -593,12 +1468,14 @@ class AnswerComposer:
             rag_context=rag_context,
             memory=memory,
         )
-        answer = self._strip_model_generated_sources(answer)
+        answer = self._postprocess_document_answer(answer, used_hits, validate_markers=self.validate_source_markers)
+        referenced_numbers = self._referenced_source_numbers(answer)
 
         sources = self.build_sources(
             used_hits,
-            max_sources=self.max_sources,
-            include_pure_neighbors=self.include_pure_neighbors_as_sources,
+            max_sources=(len(used_hits) if self.display_all_context_sources else self.max_sources),
+            include_pure_neighbors=(self.include_pure_neighbors_as_sources or self.display_all_context_sources),
             allowed_container_ids=list(self.allowed_container_ids) if self.allowed_container_ids else None,
+            referenced_source_numbers=referenced_numbers,
         )
         return answer, "document", sources

src/app.py

@@ -7,7 +7,7 @@ from huggingface_hub import snapshot_download
 from dataclasses import dataclass
 from pathlib import Path
 from threading import Lock
-from typing import Any, Dict, List, Optional, Iterable
+from typing import Any, Callable, Dict, Iterable, List, Literal, Optional, TypedDict
 from uuid import uuid4
 
 from fastapi import FastAPI, HTTPException, Request, Response
@@ -16,15 +16,22 @@ from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, Field
 
-from .retriever import LegalRetriever
-from .llm_client_groq import (
+from retriever import LegalRetriever
+from llm_client_groq import (
     DEFAULT_SYSTEM_PROMPT,
     ConversationMemory,
     GroqClient,
     classify_question,
     is_meta_question,
 )
-from .answer_composer import AnswerComposer
+from answer_composer import AnswerComposer
+from orchestrator import LegalAnswerOrchestrator, OrchestratorOptions
+
+try:
+    from langgraph.graph import StateGraph, END
+except ImportError:  # LangGraph ist nur für Workflow-Visualisierung erforderlich.
+    StateGraph = None  # type: ignore[assignment]
+    END = "__end__"  # type: ignore[assignment]
 
 
 # -----------------------------------------------------------------------------
@@ -36,16 +43,26 @@ logger = logging.getLogger(__name__)
 APP_TITLE = os.getenv("APP_TITLE", "Juristischer RAG-Prototyp")
 APP_VERSION = os.getenv("APP_VERSION", "1.1")
 
-# Datei liegt in repo/src/app.py. Für Deployment-Pfade wollen wir das Repo-Root.
+# Robuste Pfad-Ermittlung:
+# Funktioniert sowohl für:
+#   repo/app.py
+# als auch für:
+#   repo/src/app.py
 APP_DIR = Path(__file__).resolve().parent
-BASE_DIR = APP_DIR.parent
+
+if (APP_DIR / "static").exists():
+    BASE_DIR = APP_DIR
+else:
+    BASE_DIR = APP_DIR.parent
+
 
 # ---- HF Dataset -> lokale DB nach /data ziehen (Spaces) ----
+
 HF_DATASET_REPO = os.getenv("HF_DATASET_REPO", "AlixJabda/bav-ki-db")
 DATA_DIR = Path(os.getenv("DATA_DIR", "/data"))
 CHROMA_DATA_DIR = DATA_DIR / "chroma_db"
 
-# Optional Token (wenn Dataset private ist)
+# Optional Token, wenn Dataset private ist
 HF_TOKEN = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACE_HUB_TOKEN")
 
 # Nur einmal laden, wenn noch nicht vorhanden
@@ -66,43 +83,102 @@ except Exception as exc:
 def _resolve_project_path(env_name: str, default_relative: str | Path) -> str:
     raw = os.getenv(env_name)
     path = Path(raw) if raw else Path(default_relative)
+
     if not path.is_absolute():
         path = BASE_DIR / path
+
     return str(path.resolve())
 
 
+# Deine aktuelle Struktur:
+#
+# static/
+# ├── index.html
+# ├── js/
+# │   └── script.js
+# ├── styles/
+# │   └── style.css
+# └── berliner_apotheker_verein_cover.jpg
+
 STATIC_DIR = _resolve_project_path("STATIC_DIR", "static")
-INDEX_FILE = _resolve_project_path("INDEX_FILE", Path(STATIC_DIR) / "index.html")
+INDEX_FILE = _resolve_project_path("INDEX_FILE", Path("static") / "index.html")
+
+
+# --- PDF-Quelldokumente für die interaktive Fundstellen-Anzeige ---
+#
+# Suchreihenfolge:
+#   1. PDF_DIR (Env, explizit)
+#   2. DATA_DIR/pdfs   -> HF-Dataset-Snapshot auf Spaces (dort pdfs/ ablegen)
+#   3. BASE_DIR/data/pdfs bzw. BASE_DIR/data -> im Docker-Image mitgelieferte PDFs
+_PDF_ENV_DIR = os.getenv("PDF_DIR")
+
+PDF_SEARCH_DIRS: List[Path] = [
+    path
+    for path in [
+        Path(_PDF_ENV_DIR).resolve() if _PDF_ENV_DIR else None,
+        DATA_DIR / "pdfs",
+        BASE_DIR / "data" / "pdfs",
+        BASE_DIR / "data",
+    ]
+    if path is not None
+]
+
+_PDF_NAME_RE = re.compile(r"^[\w.\- ]+\.pdf$", re.I)
+
 
 SESSION_COOKIE = os.getenv("SESSION_COOKIE", "session_id")
 SESSION_COOKIE_SECURE = os.getenv("SESSION_COOKIE_SECURE", "false").lower() == "true"
 SESSION_COOKIE_MAX_AGE = int(os.getenv("SESSION_COOKIE_MAX_AGE", str(60 * 60 * 8)))
 
+
 # Keine lokalen Windows-Pfade im Deployment.
-# Standard: repo/chroma_db; per Env überschreibbar, z. B. CHROMA_PERSIST_DIR=./chroma_db.
-# Wenn Env gesetzt ist -> nutzen, sonst /data/chroma_db (Spaces), sonst fallback repo/chroma_db
-CHROMA_PERSIST_DIR = os.getenv("CHROMA_PERSIST_DIR") or str(CHROMA_DATA_DIR)
+# Standard: /data/chroma_db für Spaces; per Env überschreibbar.
+# Wichtig: Die Chroma-DB liegt im Unterordner chroma_db (dorthin lädt der
+# HF-Snapshot, siehe CHROMA_DATA_DIR). DATA_DIR selbst enthält nur eine leere
+# chroma.sqlite3 -> "verfügbare Collections=[]".
+CHROMA_PERSIST_DIR = os.getenv("CHROMA_PERSIST_DIR", str(CHROMA_DATA_DIR))
+
 if not Path(CHROMA_PERSIST_DIR).is_absolute():
     CHROMA_PERSIST_DIR = str((BASE_DIR / CHROMA_PERSIST_DIR).resolve())
+
 CHROMA_COLLECTION = os.getenv("CHROMA_COLLECTION", "rv129")
 
-# --- DEBUG: effektive Pfade prüfen (nur temporär) ---
+
+# --- DEBUG: effektive Pfade prüfen, nur temporär ---
+
 try:
+    print("DEBUG BASE_DIR:", BASE_DIR)
+    print("DEBUG STATIC_DIR:", STATIC_DIR)
+    print("DEBUG INDEX_FILE:", INDEX_FILE)
     print("DEBUG effective CHROMA_PERSIST_DIR:", CHROMA_PERSIST_DIR)
-    print("DEBUG /data listing:", os.listdir("/data")[:50])
-    print("DEBUG exists /data/chroma.sqlite3:", (Path("/data") / "chroma.sqlite3").exists())
-    print("DEBUG exists CHROMA_PERSIST_DIR/chroma.sqlite3:",
-          (Path(CHROMA_PERSIST_DIR) / "chroma.sqlite3").exists())
+
+    if Path("/data").exists():
+        print("DEBUG /data listing:", os.listdir("/data")[:50])
+        print("DEBUG exists /data/chroma.sqlite3:", (Path("/data") / "chroma.sqlite3").exists())
+
+    print(
+        "DEBUG exists CHROMA_PERSIST_DIR/chroma.sqlite3:",
+        (Path(CHROMA_PERSIST_DIR) / "chroma.sqlite3").exists(),
+    )
 except Exception as e:
     print("DEBUG path check failed:", repr(e))
+
 # --- /DEBUG ---
 
+
 DEFAULT_CONTAINER_ID = os.getenv("DEFAULT_CONTAINER_ID", "Vertrag")
 
-EMBEDDING_MODEL = os.getenv(
-    "EMBEDDING_MODEL",
-    "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
-)
+# "auto" liest das Embedding-Modell aus der Chroma-Collection-Metadata, die die
+# Ingest-Pipeline schreibt.  Damit kann die Query-Seite nie mit einem anderen
+# Modell arbeiten als der Index (die Ursache stiller Ranking-Ausfälle bzw.
+# harter Dimensionsfehler nach einem Modellwechsel wie MiniLM -> e5-base).
+EMBEDDING_MODEL = os.getenv("EMBEDDING_MODEL", "auto")
+
+# Cross-Encoder-Reranking der fusionierten Kandidaten.  Hob das Hybrid-Retrieval
+# im Golden-Eval (configs/eval_cases.json im Ingest-Repo) von 17/18 auf 18/18.
+ENABLE_RERANKER = os.getenv("ENABLE_RERANKER", "true").lower() == "true"
+RERANKER_MODEL = os.getenv("RERANKER_MODEL", "cross-encoder/mmarco-mMiniLMv2-L12-H384-v1")
+RERANKER_CANDIDATES = int(os.getenv("RERANKER_CANDIDATES", "20"))
 
 GROQ_MODEL = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
 GROQ_TEMPERATURE = float(os.getenv("GROQ_TEMPERATURE", "0.05"))
@@ -116,12 +192,24 @@ DEFAULT_MAX_SOURCES = int(os.getenv("DEFAULT_MAX_SOURCES", "5"))
 DEFAULT_RAG_CONTEXT_CHARS = int(os.getenv("DEFAULT_RAG_CONTEXT_CHARS", "12000"))
 DEFAULT_MIN_SCORE = float(os.getenv("DEFAULT_MIN_SCORE", "0.0"))
 
+
 # Wenn True, werden nur Quellen zurückgegeben, die das Modell als [Quelle n]
 # in der Antwort erwähnt. Wenn das Modell keine Marker verwendet, fällt die App
 # auf die kuratierte Quellenliste zurück.
 SOURCE_SYNC_TO_ANSWER_MARKERS = os.getenv("SOURCE_SYNC_TO_ANSWER_MARKERS", "true").lower() == "true"
 
+
+# --- Ask-Graph-Orchestrierung ---
+# Organisiert die bestehende /ask-Funktionalität als expliziten Graphen.
+# Wichtig: Es werden keine neuen fachlichen Routen eingeführt.
+
+ASK_GRAPH_ENABLED = os.getenv("ASK_GRAPH_ENABLED", "true").lower() == "true"
+ORCHESTRATOR_ENABLED = os.getenv("ORCHESTRATOR_ENABLED", "true").lower() == "true"
+MAX_ASK_GRAPH_STEPS = int(os.getenv("MAX_ASK_GRAPH_STEPS", "10"))
+
+
 _raw_origins = os.getenv("CORS_ORIGINS", "*")
+
 CORS_ORIGINS = (
     ["*"]
     if _raw_origins.strip() == "*"
@@ -130,7 +218,7 @@ CORS_ORIGINS = (
 
 
 # -----------------------------------------------------------------------------
-# App Setup
+# FastAPI-App
 # -----------------------------------------------------------------------------
 
 app = FastAPI(
@@ -139,9 +227,6 @@ app = FastAPI(
     version=APP_VERSION,
 )
 
-if os.path.isdir(STATIC_DIR):
-    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
-
 app.add_middleware(
     CORSMiddleware,
     allow_origins=CORS_ORIGINS,
@@ -150,6 +235,15 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# Static-Dateien ausliefern:
+#
+# /static/index.html
+# /static/styles/style.css
+# /static/js/script.js
+# /static/berliner_apotheker_verein_cover.jpg
+if os.path.isdir(STATIC_DIR):
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
 
 # -----------------------------------------------------------------------------
 # Session State
@@ -225,6 +319,9 @@ def _build_retriever() -> LegalRetriever:
             collection=CHROMA_COLLECTION,
             model_name=EMBEDDING_MODEL,
             default_container_id=DEFAULT_CONTAINER_ID,
+            enable_reranker=ENABLE_RERANKER,
+            reranker_model=RERANKER_MODEL,
+            reranker_candidates=RERANKER_CANDIDATES,
         )
     except TypeError:
         instance = LegalRetriever(
@@ -280,7 +377,14 @@ class Question(BaseModel):
 
     include_neighbors: bool = Field(default=True)
     include_explicit_sections: bool = Field(default=True)
-    restrict_to_default_container: bool = Field(default=True)
+    # False: Anlagen und Anhänge (z. B. Anlage 11, Dienstleistungs-Anhänge)
+    # werden mitdurchsucht.  Die Priorisierung des Hauptvertrags übernimmt das
+    # Ranking/Reranking, nicht ein harter Container-Filter, der früher ganze
+    # Fragenklassen (Beitritt, pharmazeutische Dienstleistungen) blind machte.
+    restrict_to_default_container: bool = Field(default=False)
+    verify_negative_answer: bool = Field(default=True)
+    allow_clarification: bool = Field(default=True)
+    enrich_citations: bool = Field(default=True)
     debug: bool = Field(default=False)
 
 
@@ -307,28 +411,98 @@ def _build_llm(session: SessionState) -> GroqClient:
 
 
 def _build_composer(llm: GroqClient, payload: Question) -> AnswerComposer:
+    """Baut den AnswerComposer im finalen Legal-RAG-Modus.
+
+    Wichtig: Neue Composer-Versionen liefern nummernstabile, gruppierte Quellen
+    mit Feldern wie display_title, source_numbers und canonical_refs. Diese
+    Optionen werden hier bewusst explizit gesetzt, damit die API-/UI-Schicht
+    nicht wieder auf die alte path/pages-Anzeige zurückfällt.
+    """
     allowed = [DEFAULT_CONTAINER_ID] if payload.restrict_to_default_container else None
 
+    kwargs: Dict[str, Any] = {
+        "max_context_chars": DEFAULT_RAG_CONTEXT_CHARS,
+        "pass_memory_to_llm_for_documents": False,
+        "allowed_container_ids": allowed,
+        "max_hits_for_context": payload.max_final_results or DEFAULT_MAX_FINAL_RESULTS,
+        "max_chunks_per_section": 4,
+        "max_sources": payload.max_sources or DEFAULT_MAX_SOURCES,
+        "min_score_for_context": DEFAULT_MIN_SCORE,
+        "include_neighbor_hits_in_context": True,
+        "include_pure_neighbors_as_sources": False,
+        "append_sources_to_answer": False,
+        # Neue Qualitätsoptionen des finalen Composer.
+        "display_all_context_sources": True,
+        "validate_source_markers": True,
+        "prefer_direct_hits_over_neighbors": True,
+    }
+
     try:
-        return AnswerComposer(
-            llm,
-            max_context_chars=DEFAULT_RAG_CONTEXT_CHARS,
-            pass_memory_to_llm_for_documents=False,
-            allowed_container_ids=allowed,
-            max_hits_for_context=payload.max_final_results or DEFAULT_MAX_FINAL_RESULTS,
-            max_chunks_per_section=4,
-            max_sources=payload.max_sources or DEFAULT_MAX_SOURCES,
-            min_score_for_context=DEFAULT_MIN_SCORE,
-            include_neighbor_hits_in_context=True,
-            include_pure_neighbors_as_sources=False,
-            append_sources_to_answer=False,
+        return AnswerComposer(llm, **kwargs)
+    except TypeError as exc:
+        logger.warning(
+            "AnswerComposer unterstützt nicht alle finalen Optionen; "
+            "falle auf kompatible Minimalinitialisierung zurück: %s",
+            exc,
         )
-    except TypeError:
-        return AnswerComposer(
-            llm,
-            max_context_chars=DEFAULT_RAG_CONTEXT_CHARS,
-            pass_memory_to_llm_for_documents=False,
+        legacy_keys = {
+            "max_context_chars",
+            "pass_memory_to_llm_for_documents",
+            "allowed_container_ids",
+            "max_hits_for_context",
+            "max_chunks_per_section",
+            "max_sources",
+            "min_score_for_context",
+            "include_neighbor_hits_in_context",
+            "include_pure_neighbors_as_sources",
+            "append_sources_to_answer",
+        }
+        legacy_kwargs = {key: value for key, value in kwargs.items() if key in legacy_keys}
+        try:
+            return AnswerComposer(llm, **legacy_kwargs)
+        except TypeError as exc2:
+            logger.warning(
+                "AnswerComposer unterstützt nur Minimalparameter; "
+                "Quellenqualität kann eingeschränkt sein: %s",
+                exc2,
+            )
+            return AnswerComposer(
+                llm,
+                max_context_chars=DEFAULT_RAG_CONTEXT_CHARS,
+                pass_memory_to_llm_for_documents=False,
+            )
+
+
+def _build_orchestrator(
+    retriever_instance: LegalRetriever,
+    composer: AnswerComposer,
+    payload: Question,
+) -> LegalAnswerOrchestrator:
+    options = OrchestratorOptions(
+        top_k=payload.top_k or DEFAULT_TOP_K,
+        fetch_k=payload.fetch_k or DEFAULT_FETCH_K,
+        max_final_results=payload.max_final_results or DEFAULT_MAX_FINAL_RESULTS,
+        max_sources=payload.max_sources or DEFAULT_MAX_SOURCES,
+        include_neighbors=payload.include_neighbors,
+        include_explicit_sections=payload.include_explicit_sections,
+        restrict_to_default_container=payload.restrict_to_default_container,
+        default_container_id=DEFAULT_CONTAINER_ID,
+        min_score=DEFAULT_MIN_SCORE,
+        enable_negative_recheck=payload.verify_negative_answer,
+        enable_clarification=payload.allow_clarification,
+        enrich_citations_with_canonical_refs=payload.enrich_citations,
+        debug=payload.debug,
+    )
+    try:
+        return LegalAnswerOrchestrator(
+            retriever_instance,
+            composer,
+            options=options,
+            question_classifier=classify_question,
+            meta_detector=is_meta_question,
         )
+    except TypeError:
+        return LegalAnswerOrchestrator(retriever_instance, composer, options=options)
 
 
 def _retrieve_hits(payload: Question) -> List[Dict[str, Any]]:
@@ -387,33 +561,213 @@ def _page_value(hit: Dict[str, Any]) -> Optional[str]:
     return None
 
 
+def _list_value(*values: Any) -> List[Any]:
+    """Gibt die erste nicht-leere Listen-/Skalarangabe als Liste zurück."""
+    for value in values:
+        if value is None or value == "":
+            continue
+        if isinstance(value, (list, tuple, set)):
+            return [item for item in value if item is not None and item != ""]
+        return [value]
+    return []
+
+
+def _int_list(*values: Any) -> List[int]:
+    out: List[int] = []
+    for value in _list_value(*values):
+        try:
+            number = int(value)
+        except (TypeError, ValueError):
+            continue
+        if number not in out:
+            out.append(number)
+    return sorted(out)
+
+
+def _int_or_none(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _highlight_text_from_hit(hit: Dict[str, Any], *, max_chars: int = 2000) -> str:
+    """Chunk-Text für die PDF-Hervorhebung, ohne konstruierten Kontext-Header.
+
+    Die Ingest-Pipeline stellt jedem Chunk eine Zeile "Container · § x Titel"
+    voran, die im PDF nicht existiert und daher nicht gematcht werden kann.
+    """
+    text = str(hit.get("text") or hit.get("document") or "").strip()
+    if not text:
+        return ""
+    head, sep, rest = text.partition("\n\n")
+    if sep and " · " in head and len(head) <= 200 and rest.strip():
+        text = rest.strip()
+    return text[:max_chars]
+
+
+def _highlights_from_hit(hit: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Normalisiert die Hervorhebungsliste einer Quelle bzw. eines Raw-Hits."""
+    metadata = hit.get("metadata") or {}
+
+    existing = hit.get("highlights")
+    if isinstance(existing, list) and existing:
+        out = []
+        for entry in existing:
+            if not isinstance(entry, dict):
+                continue
+            text = str(entry.get("text") or "").strip()
+            if not text:
+                continue
+            out.append(
+                {
+                    "page_start": _int_or_none(entry.get("page_start")),
+                    "page_end": _int_or_none(entry.get("page_end")) or _int_or_none(entry.get("page_start")),
+                    "text": text[:2000],
+                }
+            )
+        return out
+
+    text = _highlight_text_from_hit(hit)
+    if not text:
+        return []
+
+    page_start = _int_or_none(_coalesce(hit.get("page_start"), metadata.get("page_start")))
+    page_end = _int_or_none(_coalesce(hit.get("page_end"), metadata.get("page_end"))) or page_start
+    return [{"page_start": page_start, "page_end": page_end, "text": text}]
+
+
+def _canonical_refs_from_hit(hit: Dict[str, Any]) -> List[str]:
+    metadata = hit.get("metadata") or {}
+    refs = [
+        str(ref).strip()
+        for ref in _list_value(hit.get("canonical_refs"), metadata.get("canonical_refs"))
+        if str(ref).strip()
+    ]
+
+    single = _coalesce(hit.get("canonical_ref"), metadata.get("canonical_ref"))
+    if single is not None and str(single).strip() and str(single).strip() not in refs:
+        refs.append(str(single).strip())
+
+    return refs
+
+
+def _source_marker(numbers: List[int]) -> str:
+    if not numbers:
+        return ""
+    if len(numbers) == 1:
+        return f"[Quelle {numbers[0]}]"
+    return "[Quellen " + ", ".join(str(n) for n in numbers) + "]"
+
+
+def _format_source_display_title(source: Dict[str, Any]) -> str:
+    """Erzeugt eine UI-fertige, nummernstabile Quellenanzeige."""
+    marker = _coalesce(source.get("source_label"), source.get("source_marker")) or _source_marker(
+        _int_list(source.get("source_numbers"), source.get("source_number"))
+    )
+
+    container = _coalesce(source.get("container"), "Unbekannt")
+    section = _coalesce(source.get("section"), "ohne Abschnitt")
+    path = _coalesce(source.get("path"), source.get("section_path"))
+    if not path:
+        path = f"{container}::{section}"
+
+    pages = _coalesce(source.get("page_range"), source.get("pages"), "?")
+    canonical_refs = [
+        str(ref).strip()
+        for ref in _list_value(source.get("canonical_refs"), source.get("canonical_ref"))
+        if str(ref).strip()
+    ]
+
+    # Keine redundante Anzeige "§ 6 (§ 6)".
+    canonical_refs = [ref for ref in dict.fromkeys(canonical_refs) if ref != section]
+    ref_part = f" ({'; '.join(canonical_refs[:4])})" if canonical_refs else ""
+
+    role = ""
+    kinds = set(source.get("retrieval_kinds") or [])
+    if kinds == {"neighbor"}:
+        role = " · Kontext/Nachbar"
+
+    return f"{marker} {path}{ref_part}, Seiten {pages}{role}".strip()
+
+
 def _source_from_hit(hit: Dict[str, Any], *, source_number: Optional[int] = None) -> Dict[str, Any]:
     """
     Einheitliche Quellennormalisierung.
 
-    Unterstützt sowohl Raw-Retriever-Hits als auch bereits kuratierte Composer-
-    Quellen. Dadurch verschwindet im Frontend "Seiten undefined".
+    Unterstützt Raw-Retriever-Hits und bereits kuratierte Composer-Quellen.
+    Anders als die ältere Version bewahrt sie Composer-Felder wie
+    display_title, source_numbers und canonical_refs, damit die UI nicht wieder
+    auf bloße path/pages-Ausgaben zurückfällt.
     """
     metadata = hit.get("metadata") or {}
 
-    source = {
-        "source_number": source_number or hit.get("source_number"),
-        "container": _coalesce(hit.get("container"), hit.get("container_id"), metadata.get("container_id")),
-        "section": _coalesce(hit.get("section"), hit.get("section_id"), metadata.get("section_id")),
-        "path": _coalesce(hit.get("path"), hit.get("section_path"), metadata.get("section_path")),
-        "pages": _page_value(hit),
+    explicit_number = source_number if source_number is not None else _coalesce(
+        hit.get("source_number"),
+        metadata.get("source_number"),
+    )
+    source_numbers = _int_list(
+        hit.get("source_numbers"),
+        metadata.get("source_numbers"),
+        explicit_number,
+    )
+
+    pages = _page_value(hit)
+    container = _coalesce(hit.get("container"), hit.get("container_id"), metadata.get("container_id"))
+    section = _coalesce(hit.get("section"), hit.get("section_id"), metadata.get("section_id"))
+    canonical_refs = _canonical_refs_from_hit(hit)
+    canonical_ref = _coalesce(hit.get("canonical_ref"), metadata.get("canonical_ref"))
+    if canonical_ref is None and canonical_refs:
+        canonical_ref = canonical_refs[0]
+
+    path = _coalesce(
+        hit.get("path"),
+        hit.get("section_path"),
+        metadata.get("path"),
+        metadata.get("section_path"),
+    )
+    if not path and container and section:
+        path = f"{container}::{section}"
+
+    source: Dict[str, Any] = {
+        "source_number": explicit_number,
+        "source_numbers": source_numbers,
+        "source_marker": _coalesce(hit.get("source_marker"), metadata.get("source_marker"), _source_marker(source_numbers)),
+        "source_label": _coalesce(hit.get("source_label"), metadata.get("source_label"), _source_marker(source_numbers)),
+        "container": container,
+        "section": section,
+        "canonical_ref": canonical_ref,
+        "canonical_refs": canonical_refs,
+        "path": path,
+        "pages": pages,
+        "page_range": pages,
         "chunk_index": _coalesce(
             hit.get("chunk_index"),
             hit.get("chunk_index_in_section"),
+            metadata.get("chunk_index"),
             metadata.get("chunk_index_in_section"),
         ),
+        # PDF-Locator für die interaktive Fundstellen-Anzeige in der UI.
+        "page_start": _int_or_none(_coalesce(hit.get("page_start"), metadata.get("page_start"))),
+        "page_end": _int_or_none(_coalesce(hit.get("page_end"), metadata.get("page_end"), hit.get("page_start"), metadata.get("page_start"))),
+        "source_file": _coalesce(hit.get("source_file"), metadata.get("source_file")),
+        "doc_id": _coalesce(hit.get("doc_id"), metadata.get("doc_id")),
+        "highlights": _highlights_from_hit(hit),
+        "legal_unit_id": _coalesce(hit.get("legal_unit_id"), metadata.get("legal_unit_id")),
+        "parent_unit_id": _coalesce(hit.get("parent_unit_id"), metadata.get("parent_unit_id")),
+        "chunk_kind": _coalesce(hit.get("chunk_kind"), metadata.get("chunk_kind")),
+        "unit_type": _coalesce(hit.get("unit_type"), metadata.get("unit_type")),
         "score": hit.get("score"),
         "rank_score": hit.get("rank_score"),
-        "retrieval_kinds": hit.get("retrieval_kinds", []),
+        "retrieval_kinds": hit.get("retrieval_kinds", metadata.get("retrieval_kinds", [])),
+        "display_label": _coalesce(hit.get("display_label"), metadata.get("display_label")),
+        "display_title": _coalesce(hit.get("display_title"), metadata.get("display_title")),
     }
 
-    # Frontend-Kompatibilität: einige UIs erwarten page_range.
-    source["page_range"] = source["pages"]
+    if not source["display_title"]:
+        source["display_title"] = _format_source_display_title(source)
+    if not source["display_label"]:
+        source["display_label"] = source["display_title"]
 
     return source
 
@@ -424,7 +778,7 @@ def _extract_answer_source_numbers(answer: str) -> List[int]:
         [Quelle 1], [Quelle 2], ...
     """
     nums: List[int] = []
-    for m in re.finditer(r"\[Quelle\s+(\d+)\]", answer or "", flags=re.I):
+    for m in re.finditer(r"\[Quelle\s+(\d+)(?:[^\]]*)\]", answer or "", flags=re.I):
         try:
             nums.append(int(m.group(1)))
         except ValueError:
@@ -432,21 +786,117 @@ def _extract_answer_source_numbers(answer: str) -> List[int]:
     return list(dict.fromkeys(nums))
 
 
+def _merge_source(existing: Dict[str, Any], incoming: Dict[str, Any]) -> Dict[str, Any]:
+    """Führt gruppierbare Quellen zusammen, ohne Nummern/Fundstellen zu verlieren."""
+    merged = dict(existing)
+
+    numbers = _int_list(existing.get("source_numbers"), existing.get("source_number"), incoming.get("source_numbers"), incoming.get("source_number"))
+    refs = [
+        str(ref).strip()
+        for ref in _list_value(existing.get("canonical_refs"), existing.get("canonical_ref"), incoming.get("canonical_refs"), incoming.get("canonical_ref"))
+        if str(ref).strip()
+    ]
+    refs = list(dict.fromkeys(refs))
+
+    kinds = list(dict.fromkeys(
+        list(existing.get("retrieval_kinds") or []) + list(incoming.get("retrieval_kinds") or [])
+    ))
+
+    merged["source_numbers"] = numbers
+    merged["source_number"] = numbers[0] if numbers else _coalesce(existing.get("source_number"), incoming.get("source_number"))
+    merged["source_marker"] = _source_marker(numbers) or _coalesce(existing.get("source_marker"), incoming.get("source_marker"))
+    merged["source_label"] = merged["source_marker"]
+    merged["canonical_refs"] = refs
+    merged["canonical_ref"] = _coalesce(existing.get("canonical_ref"), incoming.get("canonical_ref"), refs[0] if refs else None)
+    merged["retrieval_kinds"] = kinds
+
+    # Behalte den höchsten Score, ohne None/Strings zu erzwingen.
+    for key in ("score", "rank_score"):
+        try:
+            old_score = float(existing.get(key) or 0.0)
+            new_score = float(incoming.get(key) or 0.0)
+            merged[key] = max(old_score, new_score)
+        except (TypeError, ValueError):
+            merged[key] = _coalesce(existing.get(key), incoming.get(key))
+
+    # Bei mehreren Chunks derselben Section ist chunk_index für die Anzeige nicht
+    # mehr sinnvoll eindeutig. Nur behalten, wenn identisch.
+    if existing.get("chunk_index") != incoming.get("chunk_index"):
+        merged["chunk_index"] = None
+
+    # PDF-Locator zusammenführen: Seitenbereich aufspannen, Datei behalten,
+    # Hervorhebungen beider Quellen sammeln.
+    starts = [p for p in (_int_or_none(existing.get("page_start")), _int_or_none(incoming.get("page_start"))) if p is not None]
+    ends = [p for p in (_int_or_none(existing.get("page_end")), _int_or_none(incoming.get("page_end"))) if p is not None]
+    merged["page_start"] = min(starts) if starts else None
+    merged["page_end"] = max(ends) if ends else merged["page_start"]
+    merged["source_file"] = _coalesce(existing.get("source_file"), incoming.get("source_file"))
+    merged["doc_id"] = _coalesce(existing.get("doc_id"), incoming.get("doc_id"))
+
+    highlights: List[Dict[str, Any]] = []
+    seen_highlights: set = set()
+    for entry in list(existing.get("highlights") or []) + list(incoming.get("highlights") or []):
+        if not isinstance(entry, dict):
+            continue
+        text = str(entry.get("text") or "").strip()
+        if not text:
+            continue
+        dedupe_key = (entry.get("page_start"), text[:120])
+        if dedupe_key in seen_highlights:
+            continue
+        seen_highlights.add(dedupe_key)
+        highlights.append(entry)
+    merged["highlights"] = highlights[:8]
+
+    merged["display_title"] = _format_source_display_title(merged)
+    merged["display_label"] = merged["display_title"]
+    return merged
+
+
+def _source_dedupe_key(src: Dict[str, Any]) -> tuple[Any, ...]:
+    """Dedupe-Key, der Composer-Gruppierungen respektiert."""
+    numbers = tuple(_int_list(src.get("source_numbers"), src.get("source_number")))
+    if numbers:
+        return ("numbers", numbers)
+
+    display_title = src.get("display_title")
+    if display_title:
+        return ("display", display_title)
+
+    canonical_refs = tuple(src.get("canonical_refs") or [])
+    return (
+        "location",
+        src.get("container"),
+        src.get("section"),
+        src.get("pages") or src.get("page_range"),
+        canonical_refs,
+    )
+
+
 def _dedupe_sources(sources: Iterable[Dict[str, Any]], *, max_sources: int) -> List[Dict[str, Any]]:
-    seen = set()
-    out: List[Dict[str, Any]] = []
+    """Dedupliziert Quellen, ohne Composer-Felder zu verlieren.
+
+    Die alte Variante normalisierte jede Quelle auf path/pages/chunk_index zurück
+    und zerstörte dadurch display_title, source_numbers und canonical_refs.
+    """
+    grouped: Dict[tuple[Any, ...], Dict[str, Any]] = {}
+    order: List[tuple[Any, ...]] = []
 
     for raw in sources:
         src = _source_from_hit(raw)
-        key = (src.get("container"), src.get("section"), src.get("pages"), src.get("chunk_index"))
-        if key in seen:
-            continue
-        seen.add(key)
-        out.append(src)
-        if len(out) >= max_sources:
-            break
 
-    return out
+        # Wenn keine Nummern vorhanden sind, gruppiere gleiche Norm/Seiten, nicht
+        # einzelne Chunk-Indizes. Das verhindert doppelte "Vertrag::§ 6"-Zeilen.
+        key = _source_dedupe_key(src)
+        if key not in grouped:
+            grouped[key] = src
+            order.append(key)
+        else:
+            grouped[key] = _merge_source(grouped[key], src)
+
+    out = [grouped[key] for key in order]
+    out.sort(key=lambda s: (_int_list(s.get("source_numbers"), s.get("source_number")) or [10_000])[0])
+    return out[:max_sources]
 
 
 def _build_sources_from_composer_or_hits(
@@ -461,7 +911,7 @@ def _build_sources_from_composer_or_hits(
         try:
             raw_sources = composer.build_sources(
                 hits,
-                max_sources=max_sources,
+                max_sources=max(max_sources, min(len(hits), DEFAULT_MAX_FINAL_RESULTS)),
                 include_pure_neighbors=False,
                 allowed_container_ids=allowed,
             )
@@ -470,12 +920,138 @@ def _build_sources_from_composer_or_hits(
             try:
                 raw_sources = composer.build_sources(hits, max_sources=max_sources)
                 return _dedupe_sources(raw_sources, max_sources=max_sources)
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Composer build_sources fallback failed: %s", exc)
 
     return _dedupe_sources(hits, max_sources=max_sources)
 
 
+def _sources_cover_cited_numbers(sources: List[Dict[str, Any]], cited_numbers: List[int]) -> bool:
+    if not cited_numbers:
+        return True
+    covered = set()
+    for source in sources:
+        covered.update(_int_list(source.get("source_numbers"), source.get("source_number")))
+    return set(cited_numbers).issubset(covered)
+
+
+def _sources_for_cited_numbers_from_raw_hits(
+    cited_numbers: List[int],
+    hits: List[Dict[str, Any]],
+    *,
+    max_sources: int,
+) -> List[Dict[str, Any]]:
+    """Letzter Fallback: mappt [Quelle n] auf Treffer n.
+
+    Dieser Pfad ist nur ein Sicherheitsnetz. Bevorzugt werden Composer-Sources,
+    weil der Composer den Kontext sortiert/dedupliziert und die Nummern korrekt
+    kennt.
+    """
+    cited_sources: List[Dict[str, Any]] = []
+    for num in cited_numbers:
+        idx = num - 1
+        if 0 <= idx < len(hits):
+            cited_sources.append(_source_from_hit(hits[idx], source_number=num))
+    return _dedupe_sources(cited_sources, max_sources=max_sources)
+
+
+_FINE_REF_RE = re.compile(
+    r"§\s*(\d{1,3}[a-z]?)\s+Abs\.\s*(\d+[a-z]?)\s+Buchst\.\s*([a-z])",
+    flags=re.I,
+)
+
+
+def _evidence_blob(sources: List[Dict[str, Any]], hits: List[Dict[str, Any]]) -> str:
+    parts: List[str] = []
+    for item in list(sources or []) + list(hits or []):
+        metadata = item.get("metadata") or {}
+        parts.extend(
+            str(value)
+            for value in [
+                item.get("canonical_ref"),
+                item.get("canonical_refs"),
+                item.get("section"),
+                item.get("section_id"),
+                item.get("path"),
+                item.get("text"),
+                item.get("document"),
+                metadata.get("canonical_ref"),
+                metadata.get("section_id"),
+                metadata.get("text"),
+            ]
+            if value
+        )
+    return " ".join(parts).lower()
+
+
+def _sanitize_unsupported_fine_references(
+    answer: str,
+    *,
+    sources: List[Dict[str, Any]],
+    hits: List[Dict[str, Any]],
+) -> str:
+    """Entschärft erfundene Feinfundstellen wie '§ 6 Abs. 1 Buchst. a'.
+
+    Wenn die genaue Buchstabenfundstelle nicht im Kontext/Metadaten belegt ist,
+    wird auf die belastbarere Absatzfundstelle zurückgeführt.
+    """
+    if not answer:
+        return answer
+
+    evidence = _evidence_blob(sources, hits)
+
+    def repl(match: re.Match[str]) -> str:
+        para, abs_no, letter = match.group(1), match.group(2), match.group(3).lower()
+        exact_patterns = [
+            f"§ {para} abs. {abs_no} buchst. {letter}",
+            f"§{para} abs. {abs_no} buchst. {letter}",
+            f"§ {para} absatz {abs_no} buchstabe {letter}",
+            f"§ {para} abs. {abs_no} lit. {letter}",
+        ]
+        if any(pattern in evidence for pattern in exact_patterns):
+            return match.group(0)
+        return f"§ {para} Abs. {abs_no}"
+
+    cleaned = _FINE_REF_RE.sub(repl, answer)
+
+    # Entfernt häufige Dopplung: "(§ 6 Abs. 1), § 6 Abs. 1"
+    cleaned = re.sub(
+        r"\((§\s*\d{1,3}[a-z]?\s+Abs\.\s*\d+[a-z]?)\),\s*\1",
+        r"(\1)",
+        cleaned,
+        flags=re.I,
+    )
+    return cleaned
+
+
+def _postprocess_answer(
+    composer: AnswerComposer,
+    answer: str,
+    *,
+    sources: List[Dict[str, Any]],
+    hits: List[Dict[str, Any]],
+) -> str:
+    """Zentraler letzter Antwort-Postprocessor für Composer- und Orchestratorpfad."""
+    text = answer or ""
+
+    if hasattr(composer, "_strip_model_generated_sources"):
+        try:
+            text = composer._strip_model_generated_sources(text)  # type: ignore[attr-defined]
+        except Exception as exc:
+            logger.debug("Composer source-strip postprocessing skipped: %s", exc)
+
+    if hasattr(composer, "_strip_invalid_source_markers"):
+        try:
+            # Erwartet meist used_hits/source_number-Strukturen; sources sind dafür
+            # besser geeignet als Raw-Hits.
+            text = composer._strip_invalid_source_markers(text, sources or hits)  # type: ignore[attr-defined]
+        except Exception as exc:
+            logger.debug("Composer marker postprocessing skipped: %s", exc)
+
+    text = _sanitize_unsupported_fine_references(text, sources=sources, hits=hits)
+    return text.strip()
+
+
 def _normalize_returned_sources(
     *,
     answer: str,
@@ -486,36 +1062,121 @@ def _normalize_returned_sources(
     """
     Finale API-Quellenlogik.
 
-    Ziele:
-    - Keine "undefined"-Seiten.
-    - Nur deduplizierte Quellen.
-    - Wenn das LLM [Quelle n] nennt und wir Raw-Hits haben, werden die
-      angezeigten Quellen in derselben Reihenfolge aus den Hits abgeleitet.
-    - Falls keine Marker genannt wurden, wird die kuratierte Composer-Quellenliste
-      genutzt.
+    Wichtigste Regel:
+    Composer-/Orchestrator-Sources sind der primäre Wahrheitsanker für [Quelle n].
+    Raw-Hits werden nur als Fallback verwendet. Dadurch bleiben display_title,
+    source_numbers und canonical_refs erhalten.
     """
     max_sources = payload.max_sources or DEFAULT_MAX_SOURCES
-
     cited_numbers = _extract_answer_source_numbers(answer)
-    if SOURCE_SYNC_TO_ANSWER_MARKERS and cited_numbers and hits:
-        cited_sources: List[Dict[str, Any]] = []
-        for num in cited_numbers:
-            idx = num - 1
-            if 0 <= idx < len(hits):
-                cited_sources.append(_source_from_hit(hits[idx], source_number=num))
-
-        deduped = _dedupe_sources(cited_sources, max_sources=max_sources)
-        if deduped:
-            return deduped
-
-    # Fallback: Composer-Sources normalisieren.
-    normalized = _dedupe_sources(sources, max_sources=max_sources)
+
+    normalized = _dedupe_sources(
+        sources or [],
+        max_sources=max(max_sources, len(cited_numbers), DEFAULT_MAX_SOURCES),
+    )
+
     if normalized:
-        return normalized
+        if SOURCE_SYNC_TO_ANSWER_MARKERS and cited_numbers:
+            # Zeige mindestens alle zitierten Quellen. Wenn Composer-Sources die
+            # zitierten Nummern abdecken, keine Rückabbildung auf Raw-Hits.
+            if _sources_cover_cited_numbers(normalized, cited_numbers):
+                cited_set = set(cited_numbers)
+                cited_first = [
+                    src for src in normalized
+                    if cited_set.intersection(_int_list(src.get("source_numbers"), src.get("source_number")))
+                ]
+                rest = [src for src in normalized if src not in cited_first]
+                return (cited_first + rest)[:max(max_sources, len(cited_first))]
+            fallback = _sources_for_cited_numbers_from_raw_hits(cited_numbers, hits, max_sources=max_sources)
+            if fallback:
+                return fallback
+        return normalized[:max_sources]
+
+    if SOURCE_SYNC_TO_ANSWER_MARKERS and cited_numbers and hits:
+        fallback = _sources_for_cited_numbers_from_raw_hits(cited_numbers, hits, max_sources=max_sources)
+        if fallback:
+            return fallback
 
     return _dedupe_sources(hits, max_sources=max_sources)
 
 
+_INLINE_MARKER_RE = re.compile(r"\[Quellen?\s+\d+(?:[^\]]*)\]", flags=re.I)
+
+
+def _remap_inline_source_markers(answer: str, old_to_new: Dict[int, int]) -> str:
+    """Schreibt Inline-Marker [Quelle n]/[Quellen n, m] auf die neuen Anzeigenummern um.
+
+    Unbekannte Nummern (kein Mapping vorhanden) bleiben unverändert stehen; sie
+    werden an anderer Stelle bereits als ungültige Marker entfernt.
+    """
+    if not answer or not old_to_new:
+        return answer
+
+    def repl(match: re.Match[str]) -> str:
+        mapped: List[int] = []
+        for raw in re.findall(r"\d+", match.group(0)):
+            try:
+                new = old_to_new.get(int(raw))
+            except (TypeError, ValueError):
+                new = None
+            if new is not None and new not in mapped:
+                mapped.append(new)
+        if not mapped:
+            return match.group(0)
+        mapped.sort()
+        return _source_marker(mapped)
+
+    return _INLINE_MARKER_RE.sub(repl, answer)
+
+
+def _renumber_sources_for_display(
+    answer: str,
+    sources: List[Dict[str, Any]],
+) -> Tuple[str, List[Dict[str, Any]]]:
+    """Vergibt stabile, fortlaufende Anzeigenummern (1..n) für die finalen Quellen.
+
+    Hintergrund: Die ursprünglichen [Quelle n]-Nummern sind Retrieval-Ränge aus
+    dem RAG-Kontext. Dadurch beginnt die Anzeige nicht bei 1 und enthält Lücken
+    (z. B. "[Quellen 3, 8]"). Für die UI werden die tatsächlich angezeigten
+    Quellen in ihrer Anzeige-Reihenfolge auf 1..n abgebildet und die
+    Inline-Marker im Antworttext konsistent mitgezogen. Mehrere Alt-Nummern
+    derselben Quelle (gruppierte Chunks) fallen dabei auf eine Anzeigenummer
+    zusammen.
+    """
+    if not sources:
+        return answer, sources
+
+    old_to_new: Dict[int, int] = {}
+    next_number = 1
+
+    for source in sources:
+        old_numbers = _int_list(source.get("source_numbers"), source.get("source_number"))
+        if not old_numbers:
+            continue
+
+        assigned: Optional[int] = None
+        for old in old_numbers:
+            if old in old_to_new:
+                assigned = old_to_new[old]
+                break
+        if assigned is None:
+            assigned = next_number
+            next_number += 1
+        for old in old_numbers:
+            old_to_new.setdefault(old, assigned)
+
+        marker = f"[Quelle {assigned}]"
+        source["source_number"] = assigned
+        source["source_numbers"] = [assigned]
+        source["source_marker"] = marker
+        source["source_label"] = marker
+        source["display_title"] = _format_source_display_title(source)
+        source["display_label"] = source["display_title"]
+
+    new_answer = _remap_inline_source_markers(answer, old_to_new)
+    return new_answer, sources
+
+
 def _debug_hit(hit: Dict[str, Any]) -> Dict[str, Any]:
     text = (hit.get("text") or hit.get("document") or "").strip()
     return {
@@ -534,91 +1195,621 @@ def _collection_count() -> Any:
 
 
 # -----------------------------------------------------------------------------
-# API Endpoints
+# Ask Graph Workflow
 # -----------------------------------------------------------------------------
 
-@app.post("/ask")
-def ask(payload: Question, request: Request):
-    question = _clean_question(payload.question)
-    if not question:
-        raise HTTPException(status_code=422, detail="question darf nicht leer sein.")
+AskRoute = Literal["meta", "non_meta", "legacy", "clarification"]
+AskNodeName = Literal[
+    "__start__",
+    "meta_decision",
+    "retrieve_hits",
+    "compose_answer",
+    "orchestrate_answer",
+    "normalize_sources",
+    "update_memory",
+    "build_response",
+    "__end__",
+]
 
-    session: SessionState = request.state.session
-    memory = session.get_memory()
 
-    llm = _build_llm(session)
-    composer = _build_composer(llm, payload)
+@dataclass
+class AskGraphStep:
+    """Rückgabe eines Graph-Knotens."""
+
+    next_node: AskNodeName
+    reason: str = ""
+
+
+@dataclass
+class AskGraphTraceEntry:
+    node: str
+    next_node: str
+    reason: str = ""
+    route: Optional[str] = None
+    hit_count: int = 0
+    answer_type: str = "unknown"
+
+
+@dataclass
+class AskGraphContext:
+    """
+    Gemeinsamer Zustand des /ask-Graphen.
+
+    Dieser Graph kapselt ausschließlich die bereits vorhandene Funktionalität:
+    Meta-Fragen werden ohne Retrieval beantwortet, alle anderen Fragen laufen
+    durch Retrieval, AnswerComposer, Quellennormalisierung, Memory-Update und
+    Response-Aufbau.
+    """
+
+    payload: Question
+    request: Request
+    session: SessionState
+    memory: ConversationMemory
+    llm: GroqClient
+    composer: AnswerComposer
+    question: str
+    orchestrator: Optional[LegalAnswerOrchestrator] = None
+
+    route: Optional[AskRoute] = None
+    hits: Optional[List[Dict[str, Any]]] = None
+    raw_sources: Optional[List[Dict[str, Any]]] = None
+    sources: Optional[List[Dict[str, Any]]] = None
+    answer: str = ""
+    answer_type: str = "unknown"
+    response_body: Optional[Dict[str, Any]] = None
+    orchestrator_debug: Optional[Dict[str, Any]] = None
+    needs_clarification: bool = False
+    clarification_question: Optional[str] = None
+    trace: Optional[List[AskGraphTraceEntry]] = None
+
+    def __post_init__(self) -> None:
+        if self.hits is None:
+            self.hits = []
+        if self.raw_sources is None:
+            self.raw_sources = []
+        if self.sources is None:
+            self.sources = []
+        if self.trace is None:
+            self.trace = []
+
+
+def _ask_graph_meta_decision(ctx: AskGraphContext) -> AskGraphStep:
+    """Routet Meta-Fragen, Orchestrator-Fragen und Legacy-Fallback sauber."""
+    if is_meta_question(ctx.question):
+        ctx.route = "meta"
+        return AskGraphStep("compose_answer", "meta question without retrieval")
+
+    if ORCHESTRATOR_ENABLED and ctx.orchestrator is not None:
+        ctx.route = "non_meta"
+        return AskGraphStep("orchestrate_answer", "regular question via legal orchestrator")
+
+    ctx.route = "legacy"
+    return AskGraphStep("retrieve_hits", "orchestrator unavailable or disabled; legacy retrieval")
+
+
+def _ask_graph_retrieve_hits(ctx: AskGraphContext) -> AskGraphStep:
+    """Entspricht dem bisherigen Aufruf von _retrieve_hits(payload)."""
+    ctx.hits = _retrieve_hits(ctx.payload)
+    return AskGraphStep("compose_answer", f"retrieved {len(ctx.hits)} hits")
+
+
+def _ask_graph_orchestrate_answer(ctx: AskGraphContext) -> AskGraphStep:
+    """Fachlicher Orchestrator-Knoten: Retrieval, Recheck, Antwort, Audit."""
+    if ctx.orchestrator is None:
+        ctx.route = "legacy"
+        return AskGraphStep("retrieve_hits", "orchestrator unavailable; falling back to legacy retrieval")
+
+    result = ctx.orchestrator.run(ctx.question, memory=ctx.memory)
+    ctx.answer = result.answer
+    ctx.answer_type = result.answer_type
+    ctx.hits = result.hits
+    ctx.raw_sources = result.raw_sources
+    ctx.sources = result.sources
+    ctx.needs_clarification = result.needs_clarification
+    ctx.clarification_question = result.clarification_question
+    ctx.orchestrator_debug = result.to_debug_dict()
+    if result.needs_clarification:
+        ctx.route = "clarification"
+    return AskGraphStep("normalize_sources", "answer orchestrated and audited")
+
+
+def _ask_graph_compose_answer(ctx: AskGraphContext) -> AskGraphStep:
+    """
+    Entspricht der bisherigen Antwortgenerierung im /ask-Endpoint.
+
+    Meta-Fragen werden mit leerem Kontext komponiert. Nicht-Meta-Fragen nutzen
+    weiterhin compose_with_sources, sofern vorhanden, sonst compose plus
+    Quellen-Fallback.
+    """
+    if ctx.route == "meta":
+        ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, [], memory=ctx.memory)
+        ctx.raw_sources = []
+        return AskGraphStep("normalize_sources", "meta answer composed")
+
+    if hasattr(ctx.composer, "compose_with_sources"):
+        try:
+            ctx.answer, ctx.answer_type, raw_sources = ctx.composer.compose_with_sources(
+                ctx.question,
+                ctx.hits,
+                memory=ctx.memory,
+            )
+        except TypeError:
+            ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, ctx.hits, memory=ctx.memory)
+            raw_sources = _build_sources_from_composer_or_hits(ctx.composer, ctx.hits, ctx.payload)
+    else:
+        ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, ctx.hits, memory=ctx.memory)
+        raw_sources = _build_sources_from_composer_or_hits(ctx.composer, ctx.hits, ctx.payload)
+
+    ctx.raw_sources = raw_sources
+    return AskGraphStep("normalize_sources", "answer composed")
+
+
+def _ask_graph_normalize_sources(ctx: AskGraphContext) -> AskGraphStep:
+    """Normalisiert Quellen und führt finalen Antwort-Postprocessing-Schritt aus.
+
+    Der Orchestratorpfad darf den Composer-Postprocessor nicht umgehen. Deshalb
+    werden hier Quellen zuerst nummernstabil normalisiert, danach wird die
+    Antwort gegen diese Quellen nachbearbeitet und anschließend erneut leicht
+    synchronisiert.
+    """
+    if ctx.answer_type == "document":
+        raw_input_sources = ctx.raw_sources or ctx.sources or []
+        ctx.sources = _normalize_returned_sources(
+            answer=ctx.answer,
+            sources=raw_input_sources,
+            hits=ctx.hits,
+            payload=ctx.payload,
+        )
+        ctx.answer = _postprocess_answer(
+            ctx.composer,
+            ctx.answer,
+            sources=ctx.sources,
+            hits=ctx.hits or [],
+        )
+        ctx.sources = _normalize_returned_sources(
+            answer=ctx.answer,
+            sources=ctx.sources or raw_input_sources,
+            hits=ctx.hits,
+            payload=ctx.payload,
+        )
+        # Anzeige-Nummern stabil auf 1..n abbilden (statt Retrieval-Ränge wie
+        # "[Quellen 3, 8]"). Muss als letzter Schritt laufen, damit Antworttext
+        # und Quellenliste dieselben Nummern zeigen.
+        ctx.answer, ctx.sources = _renumber_sources_for_display(ctx.answer, ctx.sources)
+    else:
+        ctx.sources = []
+
+    return AskGraphStep("update_memory", "sources normalized and answer postprocessed")
+
+
+def _ask_graph_update_memory(ctx: AskGraphContext) -> AskGraphStep:
+    """Entspricht dem bisherigen memory.add_turn(...)."""
+    ctx.memory.add_turn(
+        user_message=ctx.question,
+        assistant_message=ctx.answer,
+        question_kind=classify_question(ctx.question),
+    )
+    return AskGraphStep("build_response", "conversation memory updated")
+
+
+_PAGE_RANGE_RE = re.compile(r"(\d+)\s*[–\-]\s*(\d+)|^(\d+)$")
+
+
+def _attach_pdf_locators(sources: List[Dict[str, Any]], hits: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Sicherheitsnetz: fehlende PDF-Locator aus Hits bzw. page_range ableiten.
+
+    Composer/Orchestrator liefern die Felder normalerweise bereits mit. Ältere
+    Pfade (Legacy-Fallbacks) können sie verlieren; da der Korpus derzeit aus
+    einem Dokument besteht, ist source_file aus einem beliebigen Hit belastbar.
+    """
+    fallback_file = None
+    fallback_doc_id = None
+    for hit in hits or []:
+        metadata = hit.get("metadata") or {}
+        fallback_file = fallback_file or _coalesce(hit.get("source_file"), metadata.get("source_file"))
+        fallback_doc_id = fallback_doc_id or _coalesce(hit.get("doc_id"), metadata.get("doc_id"))
+        if fallback_file and fallback_doc_id:
+            break
+
+    for source in sources or []:
+        if not source.get("source_file") and fallback_file:
+            source["source_file"] = fallback_file
+        if not source.get("doc_id") and fallback_doc_id:
+            source["doc_id"] = fallback_doc_id
+
+        if source.get("page_start") is None:
+            match = _PAGE_RANGE_RE.search(str(source.get("page_range") or source.get("pages") or ""))
+            if match:
+                start = match.group(1) or match.group(3)
+                end = match.group(2) or start
+                source["page_start"] = _int_or_none(start)
+                source["page_end"] = _int_or_none(end)
+        if source.get("page_end") is None:
+            source["page_end"] = source.get("page_start")
+
+        if not source.get("highlights"):
+            source["highlights"] = []
+
+    return sources
+
+
+def _ask_graph_build_response(ctx: AskGraphContext) -> AskGraphStep:
+    """Baut exakt die bisherige API-Response-Struktur."""
+    _attach_pdf_locators(ctx.sources or [], ctx.hits or [])
+    ctx.response_body = {
+        "question": ctx.question,
+        "answer": ctx.answer,
+        "answer_type": ctx.answer_type,
+        "session_id": ctx.request.state.session_id,
+        "factual_question_index": ctx.memory.factual_question_count,
+        "total_turns": ctx.memory.total_turns,
+        "sources": ctx.sources or [],
+        "needs_clarification": ctx.needs_clarification,
+        "clarification_question": ctx.clarification_question,
+    }
+    return AskGraphStep("__end__", "response built")
+
+
+ASK_GRAPH_NODES: Dict[AskNodeName, Callable[[AskGraphContext], AskGraphStep]] = {
+    "meta_decision": _ask_graph_meta_decision,
+    "retrieve_hits": _ask_graph_retrieve_hits,
+    "compose_answer": _ask_graph_compose_answer,
+    "orchestrate_answer": _ask_graph_orchestrate_answer,
+    "normalize_sources": _ask_graph_normalize_sources,
+    "update_memory": _ask_graph_update_memory,
+    "build_response": _ask_graph_build_response,
+}
+
+ASK_GRAPH: Dict[str, List[Dict[str, str]]] = {
+    "__start__": [{"to": "meta_decision", "label": ""}],
+    "meta_decision": [
+        {"to": "compose_answer", "label": "meta"},
+        {"to": "orchestrate_answer", "label": "non_meta"},
+        {"to": "retrieve_hits", "label": "legacy"},
+    ],
+    "retrieve_hits": [{"to": "compose_answer", "label": ""}],
+    "orchestrate_answer": [{"to": "normalize_sources", "label": ""}],
+    "compose_answer": [{"to": "normalize_sources", "label": ""}],
+    "normalize_sources": [{"to": "update_memory", "label": ""}],
+    "update_memory": [{"to": "build_response", "label": ""}],
+    "build_response": [{"to": "__end__", "label": ""}],
+}
+
+
+class AskGraphVizState(TypedDict, total=False):
+    """Minimaler LangGraph-State nur für Visualisierung/Rendering."""
+
+    route: str
+
+
+def _ask_langgraph_passthrough(state: AskGraphVizState) -> AskGraphVizState:
+    """Dummy-Node für LangGraph-Rendering; die echte Logik bleibt in run_ask_graph."""
+    return state
+
+
+def _make_ask_langgraph_router(source: str, labels: List[str]):
+    """
+    Erzeugt einen Router für LangGraph-Visualisierung.
+
+    Für das Rendering ist nur die Mapping-Struktur wichtig. Falls der Graph
+    doch testweise ausgeführt wird, kann pro Node über '<node>_route' geroutet
+    werden; sonst wird der erste Label-Zweig genutzt.
+    """
+    default_label = labels[0]
+
+    def _router(state: AskGraphVizState) -> str:
+        return state.get(f"{source}_route", state.get("route", default_label))
+
+    return _router
+
 
-    if is_meta_question(question):
-        hits: List[Dict[str, Any]] = []
-        answer, answer_type = composer.compose(question, hits, memory=memory)
-        sources: List[Dict[str, Any]] = []
+def build_ask_workflow():
+    """
+    Baut den LangGraph-Workflow aus ASK_GRAPH.
+
+    Diese Funktion ist die stabile Schnittstelle für visualize_graph.py:
+        from app import build_ask_workflow
+        workflow = build_ask_workflow()
+        workflow.get_graph(xray=True).draw_mermaid_png()
+
+    Wenn ASK_GRAPH in app.py geändert wird, übernimmt die Visualisierung diese
+    Änderung automatisch, ohne dass visualize_graph.py angepasst werden muss.
+    """
+    if StateGraph is None:
+        raise RuntimeError(
+            "LangGraph ist nicht installiert. Bitte ausführen: pip install -U langgraph langchain-core"
+        )
+
+    workflow = StateGraph(AskGraphVizState)
+
+    node_names = set()
+    for source, edges in ASK_GRAPH.items():
+        if source not in {"__start__", "__end__"}:
+            node_names.add(source)
+        for edge in edges:
+            target = edge["to"]
+            if target not in {"__start__", "__end__"}:
+                node_names.add(target)
+
+    for node_name in sorted(node_names):
+        workflow.add_node(node_name, _ask_langgraph_passthrough)
+
+    start_edges = ASK_GRAPH.get("__start__") or []
+    if not start_edges:
+        raise RuntimeError("ASK_GRAPH benötigt eine __start__-Kante.")
+    workflow.set_entry_point(start_edges[0]["to"])
+
+    for source, edges in ASK_GRAPH.items():
+        if source in {"__start__", "__end__"}:
+            continue
+
+        labelled_edges = [edge for edge in edges if edge.get("label")]
+        plain_edges = [edge for edge in edges if not edge.get("label")]
+
+        if labelled_edges:
+            labels = [edge["label"] for edge in labelled_edges]
+            workflow.add_conditional_edges(
+                source,
+                _make_ask_langgraph_router(source, labels),
+                {edge["label"]: (END if edge["to"] == "__end__" else edge["to"]) for edge in labelled_edges},
+            )
+
+        for edge in plain_edges:
+            target = END if edge["to"] == "__end__" else edge["to"]
+            workflow.add_edge(source, target)
+
+    return workflow.compile()
+
+
+def get_ask_workflow():
+    """Alias für Visualisierungsskripte, die eine Getter-Funktion bevorzugen."""
+    return build_ask_workflow()
+
+
+# Backwards-/Convenience-Aliase für Visualisierungsskripte.
+# Wichtig: FastAPI bleibt weiterhin in der Variable `app`; der LangGraph darf
+# deshalb nicht ebenfalls `app` heißen.
+try:
+    ASK_WORKFLOW = build_ask_workflow()
+except Exception:
+    ASK_WORKFLOW = None
+
+AGENT_GRAPH = ASK_GRAPH
+ASK_LANGGRAPH_APP = ASK_WORKFLOW
+
+
+def _ask_graph_mermaid() -> str:
+    lines = ["flowchart TD"]
+    for source, edges in ASK_GRAPH.items():
+        for edge in edges:
+            target = edge["to"]
+            label = edge.get("label") or ""
+            if label:
+                lines.append(f'    {source}["{source}"] -- "{label}" --> {target}["{target}"]')
+            else:
+                lines.append(f'    {source}["{source}"] --> {target}["{target}"]')
+    return "\n".join(lines)
+
+
+def run_ask_graph(ctx: AskGraphContext) -> AskGraphContext:
+    """Führt den /ask-Graphen aus, ohne fachliche Zusatzpfade einzuführen."""
+    current: AskNodeName = "meta_decision"
+
+    for _ in range(MAX_ASK_GRAPH_STEPS):
+        node = ASK_GRAPH_NODES.get(current)
+        if node is None:
+            raise HTTPException(status_code=500, detail=f"Unbekannter Ask-Graph-Knoten: {current}")
+
+        step = node(ctx)
+        ctx.trace.append(
+            AskGraphTraceEntry(
+                node=current,
+                next_node=step.next_node,
+                reason=step.reason,
+                route=ctx.route,
+                hit_count=len(ctx.hits or []),
+                answer_type=ctx.answer_type,
+            )
+        )
+
+        if step.next_node == "__end__":
+            return ctx
+
+        current = step.next_node
+
+    raise HTTPException(
+        status_code=500,
+        detail=f"Ask-Graph nach {MAX_ASK_GRAPH_STEPS} Schritten abgebrochen.",
+    )
+
+
+def _legacy_answer_flow(ctx: AskGraphContext) -> AskGraphContext:
+    """
+    Fallback auf die bisherige monolithische /ask-Logik.
+
+    Dieser Pfad bleibt absichtlich funktionsgleich zum Graphen und dient nur
+    als schneller Rollback über ASK_GRAPH_ENABLED=false.
+    """
+    if is_meta_question(ctx.question):
+        ctx.route = "meta"
+        ctx.hits = []
+        ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, [], memory=ctx.memory)
+        ctx.sources = []
     else:
-        hits = _retrieve_hits(payload)
+        ctx.route = "non_meta"
+        ctx.hits = _retrieve_hits(ctx.payload)
 
-        if hasattr(composer, "compose_with_sources"):
+        if hasattr(ctx.composer, "compose_with_sources"):
             try:
-                answer, answer_type, raw_sources = composer.compose_with_sources(
-                    question,
-                    hits,
-                    memory=memory,
+                ctx.answer, ctx.answer_type, raw_sources = ctx.composer.compose_with_sources(
+                    ctx.question,
+                    ctx.hits,
+                    memory=ctx.memory,
                 )
             except TypeError:
-                answer, answer_type = composer.compose(question, hits, memory=memory)
-                raw_sources = _build_sources_from_composer_or_hits(composer, hits, payload)
+                ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, ctx.hits, memory=ctx.memory)
+                raw_sources = _build_sources_from_composer_or_hits(ctx.composer, ctx.hits, ctx.payload)
         else:
-            answer, answer_type = composer.compose(question, hits, memory=memory)
-            raw_sources = _build_sources_from_composer_or_hits(composer, hits, payload)
+            ctx.answer, ctx.answer_type = ctx.composer.compose(ctx.question, ctx.hits, memory=ctx.memory)
+            raw_sources = _build_sources_from_composer_or_hits(ctx.composer, ctx.hits, ctx.payload)
 
-        if answer_type == "document":
-            sources = _normalize_returned_sources(
-                answer=answer,
+        ctx.raw_sources = raw_sources
+        if ctx.answer_type == "document":
+            ctx.sources = _normalize_returned_sources(
+                answer=ctx.answer,
                 sources=raw_sources,
-                hits=hits,
-                payload=payload,
+                hits=ctx.hits,
+                payload=ctx.payload,
+            )
+            ctx.answer = _postprocess_answer(
+                ctx.composer,
+                ctx.answer,
+                sources=ctx.sources,
+                hits=ctx.hits or [],
+            )
+            ctx.sources = _normalize_returned_sources(
+                answer=ctx.answer,
+                sources=ctx.sources or raw_sources,
+                hits=ctx.hits,
+                payload=ctx.payload,
             )
         else:
-            sources = []
+            ctx.sources = []
 
-    memory.add_turn(
-        user_message=question,
-        assistant_message=answer,
-        question_kind=classify_question(question),
+    ctx.memory.add_turn(
+        user_message=ctx.question,
+        assistant_message=ctx.answer,
+        question_kind=classify_question(ctx.question),
     )
+    _ask_graph_build_response(ctx)
+    return ctx
+
 
-    response_body: Dict[str, Any] = {
+def _ask_graph_debug_payload(ctx: AskGraphContext) -> Dict[str, Any]:
+    return {
+        "ask_graph_enabled": ASK_GRAPH_ENABLED,
+        "orchestrator_enabled": ORCHESTRATOR_ENABLED,
+        "orchestrator": ctx.orchestrator_debug,
+        "workflow_trace": [entry.__dict__ for entry in (ctx.trace or [])],
+        "workflow_graph": ASK_GRAPH,
+        "workflow_mermaid": _ask_graph_mermaid(),
+        "route": ctx.route,
+        "is_meta_question": is_meta_question(ctx.question),
+        "question_kind": classify_question(ctx.question),
+        "retrieved_hit_count": len(ctx.hits or []),
+        "answer_source_numbers": _extract_answer_source_numbers(ctx.answer),
+        "raw_sources": ctx.raw_sources or [],
+        "normalized_sources": ctx.sources or [],
+        "hits": [_debug_hit(hit) for hit in (ctx.hits or [])],
+        "top_k": ctx.payload.top_k or DEFAULT_TOP_K,
+        "fetch_k": ctx.payload.fetch_k or DEFAULT_FETCH_K,
+        "max_final_results": ctx.payload.max_final_results or DEFAULT_MAX_FINAL_RESULTS,
+        "max_sources": ctx.payload.max_sources or DEFAULT_MAX_SOURCES,
+        "include_neighbors": ctx.payload.include_neighbors,
+        "include_explicit_sections": ctx.payload.include_explicit_sections,
+        "restrict_to_default_container": ctx.payload.restrict_to_default_container,
+        "source_sync_to_answer_markers": SOURCE_SYNC_TO_ANSWER_MARKERS,
+        "chroma_persist_dir": CHROMA_PERSIST_DIR,
+        "chroma_collection": CHROMA_COLLECTION,
+        "chroma_count": _collection_count(),
+    }
+
+
+# -----------------------------------------------------------------------------
+# API Endpoints
+# -----------------------------------------------------------------------------
+
+@app.post("/ask")
+def ask(payload: Question, request: Request):
+    question = _clean_question(payload.question)
+    if not question:
+        raise HTTPException(status_code=422, detail="question darf nicht leer sein.")
+
+    session: SessionState = request.state.session
+    memory = session.get_memory()
+
+    llm = _build_llm(session)
+    composer = _build_composer(llm, payload)
+    orchestrator = _build_orchestrator(get_retriever(), composer, payload) if ORCHESTRATOR_ENABLED else None
+
+    ctx = AskGraphContext(
+        payload=payload,
+        request=request,
+        session=session,
+        memory=memory,
+        llm=llm,
+        composer=composer,
+        question=question,
+        orchestrator=orchestrator,
+    )
+
+    ctx = run_ask_graph(ctx) if ASK_GRAPH_ENABLED else _legacy_answer_flow(ctx)
+
+    response_body: Dict[str, Any] = ctx.response_body or {
         "question": question,
-        "answer": answer,
-        "answer_type": answer_type,
+        "answer": ctx.answer,
+        "answer_type": ctx.answer_type,
         "session_id": request.state.session_id,
         "factual_question_index": memory.factual_question_count,
         "total_turns": memory.total_turns,
-        "sources": sources,
+        "sources": ctx.sources or [],
+        "needs_clarification": ctx.needs_clarification,
+        "clarification_question": ctx.clarification_question,
     }
 
     if payload.debug:
-        response_body["debug"] = {
-            "is_meta_question": is_meta_question(question),
-            "question_kind": classify_question(question),
-            "retrieved_hit_count": len(hits),
-            "answer_source_numbers": _extract_answer_source_numbers(answer),
-            "hits": [_debug_hit(hit) for hit in hits],
-            "top_k": payload.top_k or DEFAULT_TOP_K,
-            "fetch_k": payload.fetch_k or DEFAULT_FETCH_K,
-            "max_final_results": payload.max_final_results or DEFAULT_MAX_FINAL_RESULTS,
-            "max_sources": payload.max_sources or DEFAULT_MAX_SOURCES,
-            "include_neighbors": payload.include_neighbors,
-            "include_explicit_sections": payload.include_explicit_sections,
-            "restrict_to_default_container": payload.restrict_to_default_container,
-            "source_sync_to_answer_markers": SOURCE_SYNC_TO_ANSWER_MARKERS,
-            "chroma_persist_dir": CHROMA_PERSIST_DIR,
-            "chroma_collection": CHROMA_COLLECTION,
-            "chroma_count": _collection_count(),
-        }
+        response_body["debug"] = _ask_graph_debug_payload(ctx)
 
     return response_body
 
 
+@app.get("/pdf/{filename}")
+def get_pdf(filename: str):
+    """Liefert ein Quell-PDF für den eingebetteten Fundstellen-Viewer aus.
+
+    Es werden nur einfache PDF-Dateinamen akzeptiert (kein Pfadanteil), und
+    die Datei muss in einem der konfigurierten PDF-Verzeichnisse liegen.
+    """
+    name = os.path.basename(filename or "").strip()
+    if not name or not _PDF_NAME_RE.match(name):
+        raise HTTPException(status_code=400, detail="Ungültiger PDF-Dateiname.")
+
+    for directory in PDF_SEARCH_DIRS:
+        candidate = (directory / name).resolve()
+        try:
+            candidate.relative_to(directory.resolve())
+        except (ValueError, OSError):
+            continue
+        if candidate.is_file():
+            return FileResponse(
+                str(candidate),
+                media_type="application/pdf",
+                headers={
+                    "Content-Disposition": f'inline; filename="{name}"',
+                    "Cache-Control": "public, max-age=3600",
+                },
+            )
+
+    raise HTTPException(status_code=404, detail=f"PDF nicht gefunden: {name}")
+
+
+@app.get("/debug/workflow")
+def debug_workflow():
+    return {
+        "ok": True,
+        "ask_graph_enabled": ASK_GRAPH_ENABLED,
+        "max_ask_graph_steps": MAX_ASK_GRAPH_STEPS,
+        "langgraph_available": StateGraph is not None,
+        "graph": ASK_GRAPH,
+        "mermaid": _ask_graph_mermaid(),
+    }
+
+
+@app.get("/debug/workflow/mermaid")
+def debug_workflow_mermaid():
+    return Response(_ask_graph_mermaid(), media_type="text/plain")
+
+
 @app.get("/health")
 def health():
     return {
@@ -632,6 +1823,8 @@ def health():
         "embedding_model": EMBEDDING_MODEL,
         "groq_model": GROQ_MODEL,
         "source_sync_to_answer_markers": SOURCE_SYNC_TO_ANSWER_MARKERS,
+        "ask_graph_enabled": ASK_GRAPH_ENABLED,
+        "orchestrator_enabled": ORCHESTRATOR_ENABLED,
     }
 
 
@@ -753,4 +1946,3 @@ def index():
             detail=f"UI-Datei nicht gefunden: {INDEX_FILE}",
         )
     return FileResponse(INDEX_FILE)
-

src/llm_client_groq.py

@@ -4,11 +4,15 @@ import os
 import time
 import random
 import re
+import logging
 from typing import Optional, List, Dict, Any
 
 from groq import Groq
 
 
+logger = logging.getLogger(__name__)
+
+
 # ---------------------------------------------------------------------------
 # Frageklassifikation: Single Source of Truth
 # ---------------------------------------------------------------------------
@@ -454,31 +458,86 @@ class GroqClient:
 
     @staticmethod
     def _looks_like_augmented_document_prompt(prompt: str) -> bool:
-        """Erkennt, ob AnswerComposer bereits fachliche Instruktionen enthält."""
-        p = prompt or ""
-        return (
-            "Nutzerfrage:" in p
-            and (
-                "Du beantwortest eine juristische Sachfrage" in p
-                or "Antwortschema:" in p
-                or "Verbindliche Regeln:" in p
-            )
+        """Erkennt, ob AnswerComposer bereits fachliche Instruktionen enthält.
+
+        Wichtig: Wenn diese Erkennung fehlschlägt, hängt der Client seine
+        eigenen LEGAL_TASK_INSTRUCTIONS zusätzlich an und erzeugt zwei
+        widersprüchliche Anweisungssets im selben Prompt (z. B. "Ergebnisformel"
+        vs. "Keine Ergebnisformel").  Der Composer-Prompt nutzt Block-Header in
+        Großbuchstaben, daher wird case-insensitiv geprüft.
+        """
+        p = (prompt or "")
+        if "Nutzerfrage:" not in p:
+            return False
+        lowered = p.lower()
+        markers = (
+            "du beantwortest eine juristische sachfrage",
+            "antwortschema",
+            "verbindliche regeln:",
+            "evidence first",
         )
+        return any(marker in lowered for marker in markers)
 
     @staticmethod
     def _source_marker_count(rag_context: str) -> int:
         return len(set(re.findall(r"\[Quelle\s+\d+\]", rag_context or "")))
 
     def _call_chat_completion(self, messages: List[Dict[str, str]], **kwargs: Any) -> str:
+        """Call Groq with a locked model.
+
+        Production safety rule:
+        - The billed Groq model is always `self.model`, i.e. the model configured
+          when `GroqClient` is instantiated, typically from `GROQ_MODEL` in app.py.
+        - Per-call model overrides through kwargs are rejected instead of being
+          silently accepted. This prevents accidental billing of other models such
+          as `openai/gpt-oss-120b` or `qwen/qwen3-32b`.
+        - `service_tier` overrides are also rejected here. The app should not
+          switch Groq billing tiers from arbitrary downstream calls.
+        """
+        blocked_model = kwargs.pop("model", None)
+        if blocked_model is not None and str(blocked_model) != str(self.model):
+            raise RuntimeError(
+                "Blocked Groq model override: "
+                f"requested={blocked_model!r}, configured={self.model!r}. "
+                "Only the configured model may be used for billing."
+            )
+
+        blocked_service_tier = kwargs.pop("service_tier", None)
+        if blocked_service_tier is not None:
+            raise RuntimeError(
+                "Blocked Groq service_tier override: "
+                f"requested={blocked_service_tier!r}. "
+                "Billing-tier selection must not be changed per request."
+            )
+
+        actual_model = self.model
+        temperature = kwargs.pop("temperature", self.temperature)
+        max_tokens = kwargs.pop("max_tokens", self.max_tokens)
+
+        if kwargs:
+            logger.warning(
+                "Ignoring unsupported Groq call kwargs",
+                extra={"ignored_kwargs": sorted(kwargs.keys())},
+            )
+
+        logger.info(
+            "calling Groq chat completion",
+            extra={
+                "groq_model": actual_model,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            },
+        )
+
         last_err: Optional[Exception] = None
 
         for attempt in range(self.max_retries + 1):
             try:
                 response = self.client.chat.completions.create(
-                    model=kwargs.get("model", self.model),
+                    model=actual_model,
                     messages=messages,
-                    temperature=kwargs.get("temperature", self.temperature),
-                    max_tokens=kwargs.get("max_tokens", self.max_tokens),
+                    temperature=temperature,
+                    max_tokens=max_tokens,
                 )
                 content = response.choices[0].message.content
                 return content or ""

src/orchestrator.py

@@ -0,0 +1,1220 @@
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple, TYPE_CHECKING
+
+from llm_client_groq import classify_question, is_meta_question
+
+if TYPE_CHECKING:
+    from llm_client_groq import ConversationMemory
+else:
+    ConversationMemory = Any  # type: ignore[assignment]
+
+# ---------------------------------------------------------------------------
+# Regexes and lightweight legal intent detection
+# ---------------------------------------------------------------------------
+
+NORM_REF_RE = re.compile(
+    r"§{1,2}\s*(?P<section>\d+[a-zA-Z]?)"
+    r"(?:\s*(?:-|–|bis)\s*(?P<section_to>\d+[a-zA-Z]?))?"
+    r"(?:\s*(?:Abs\.|Absatz)\s*(?P<subsection>\d+[a-zA-Z]?))?"
+    r"(?:\s*Satz\s*(?P<sentence>\d+[a-zA-Z]?))?"
+    r"(?:\s*(?:Nr\.|Nummer)\s*(?P<number>\d+[a-zA-Z]?))?"
+    r"(?:\s*(?:Buchst\.|Buchstabe|lit\.)\s*(?P<letter>[a-zA-Z]))?",
+    re.I,
+)
+
+SOURCE_MARKER_RE = re.compile(r"\[Quelle\s+(\d+)(?:[^\]]*)\]", re.I)
+SOURCE_MARKER_WITH_OPTIONAL_REF_RE = re.compile(
+    r"\[Quelle\s+(\d+)(?:[^\]]*)\]"
+    r"(?:\s*\(§[^)]{1,120}\))?",
+    re.I,
+)
+ORPHAN_LEGAL_REF_PAREN_RE = re.compile(r"\(§\s*\d{1,3}[a-z]?(?:\s+[^)]{0,80})?\)", re.I)
+NEGATIVE_ANSWER_RE = re.compile(
+    r"\b(keine\s+(relevante\s+)?textstelle|nicht\s+(geregelt|enthalten|auffindbar)|"
+    r"keine\s+(regelung|informationen|aussage)|nicht\s+belastbar\s+ableitbar|"
+    r"kann\s+.*?nicht\s+(festgestellt|beantwortet)\s+werden)\b",
+    re.I,
+)
+
+# Fine-grained citation fragments generated by the LLM must be verified against
+# actual source metadata.  In practice, models often over-specialise references
+# such as "§ 6 Abs. 1 Buchst. a" although the underlying chunk only supports
+# "§ 6 Abs. 1".  The orchestrator therefore downgrades unsupported fine refs
+# instead of passing them through as if they were verified citations.
+FINE_BUCHST_REF_RE = re.compile(
+    r"§\s*(?P<section>\d{1,3}[a-z]?)\s+"
+    r"(?:Abs\.|Absatz)\s*(?P<subsection>\d{1,3}[a-z]?)\s+"
+    r"(?:Buchst\.|Buchstabe|lit\.)\s*(?P<letter>[a-z])",
+    re.I,
+)
+
+CITATION_PAREN_RE = re.compile(
+    r"(?P<marker>\[Quelle\s+\d+(?:[^\]]*)\])\s*"
+    r"\((?P<ref>§[^)]{1,120})\)",
+    re.I,
+)
+
+DANGLING_CITATION_GRAMMAR_REPLACEMENTS: Tuple[Tuple[re.Pattern[str], str], ...] = (
+    # Remove orphan legal-ref parentheses that remain after invalid source markers
+    # were stripped, e.g. "[Quelle 1] (§ 6) und (§ 6)".
+    (re.compile(r"(\[Quelle\s+\d+(?:[^\]]*)\](?:\s*\(§[^)]{1,120}\))?)\s+und\s+\(§[^)]{1,120}\)", re.I), r"\1"),
+    (re.compile(r"(\[Quelle\s+\d+(?:[^\]]*)\](?:\s*\(§[^)]{1,120}\))?)\s*,\s*\(§[^)]{1,120}\)", re.I), r"\1"),
+    (re.compile(r"\s+(?:und|oder)\s+\(§[^)]{1,120}\)", re.I), r""),
+    (re.compile(r"\s+und\s+(beschrieben|genannt|geregelt|dargelegt|aufgeführt)\b", re.I), r" \1"),
+    (re.compile(r"\bwie\s+in\s+([^.;:\n]{1,160}?)\s+und\s+(beschrieben|genannt|geregelt|dargelegt)\b", re.I), r"wie in \1 \2"),
+    (re.compile(r"\bdie\s+in\s+den\s+Quellen\s+([^.;:\n]{1,160}?)\s+und\s+genannt\s+sind", re.I), r"die in \1 genannt sind"),
+    (re.compile(r"\bdie\s+in\s+([^.;:\n]{1,160}?)\s+und\s+genannt\s+sind", re.I), r"die in \1 genannt sind"),
+    (re.compile(r"\bund\s+weiteren\s+Quellen\s+(dargelegt|beschrieben|genannt)\s+(sind|ist)", re.I), r"\1 \2"),
+)
+
+DEFINITION_RE = re.compile(
+    r"\b(was\s+(versteht|bedeutet)|wie\s+definiert|definition|legaldefinition|"
+    r"begriff|unter\s+[„\"']?[^?]+[”\"']?\s+versteht)\b",
+    re.I,
+)
+ENUMERATION_RE = re.compile(
+    r"\b(welche|alle|sämtliche|liste|nennt|kriterien|voraussetzungen|tatbestandsmerkmale|"
+    r"bestandteile|anforderungen|fälle|maßnahmen|regelt\s+§)\b",
+    re.I,
+)
+COMPARISON_RE = re.compile(r"\b(unterschied|vergleiche|vergleich|gegenüber|vs\.?|versus)\b", re.I)
+CLARIFICATION_RISK_RE = re.compile(
+    r"\b(das|dies|diese|der\s+fall|so\s+ein\s+fall|dort|hierbei|teilnahme|anspruch|"
+    r"abrechnung|pflicht|folge|konsequenz)\b",
+    re.I,
+)
+
+BUILTIN_QUERY_EXPANSIONS: Dict[str, List[str]] = {
+    "nicht verfügbar": ["Nichtverfügbarkeit", "lieferfähig", "nicht lieferbar", "Lieferengpass", "Verfügbarkeit"],
+    "beitritt": ["teilnehmen", "Teilnahme", "Mitgliedsverband", "DAV", "Erklärung", "beitreten"],
+    "auseinzelung": ["Teilmenge", "Auseinzelung", "einzelne Einheit", "Packung", "Entnahme"],
+    "pharmazeutische dienstleistungen": ["pharmazeutische Dienstleistungen", "Anlage 11", "Anspruchsvoraussetzungen", "Vergütung", "Abrechnung"],
+    "wunscharzneimittel": ["Wunscharzneimittel", "Kostenerstattung", "anderes Fertigarzneimittel", "§§ 11 bis 14"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Public dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass(slots=True, frozen=True)
+class NormReference:
+    section: str
+    section_to: str | None = None
+    subsection: str | None = None
+    sentence: str | None = None
+    number: str | None = None
+    letter: str | None = None
+
+    @property
+    def section_id(self) -> str:
+        return f"§ {self.section}"
+
+    @property
+    def canonical_ref(self) -> str:
+        parts = [self.section_id]
+        if self.subsection:
+            parts.append(f"Abs. {self.subsection}")
+        if self.sentence:
+            parts.append(f"Satz {self.sentence}")
+        if self.number:
+            parts.append(f"Nr. {self.number}")
+        if self.letter:
+            parts.append(f"Buchst. {self.letter.lower()}")
+        return " ".join(parts)
+
+
+@dataclass(slots=True)
+class QuestionAnalysis:
+    question: str
+    question_kind: str
+    intent: str
+    norm_references: List[NormReference] = field(default_factory=list)
+    query_terms: List[str] = field(default_factory=list)
+    expanded_terms: List[str] = field(default_factory=list)
+    needs_clarification: bool = False
+    clarification_question: str | None = None
+    reasons: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "question": self.question,
+            "question_kind": self.question_kind,
+            "intent": self.intent,
+            "norm_references": [asdict(ref) | {"canonical_ref": ref.canonical_ref} for ref in self.norm_references],
+            "query_terms": list(self.query_terms),
+            "expanded_terms": list(self.expanded_terms),
+            "needs_clarification": self.needs_clarification,
+            "clarification_question": self.clarification_question,
+            "reasons": list(self.reasons),
+        }
+
+
+@dataclass(slots=True)
+class RetrievalAssessment:
+    hit_count: int = 0
+    direct_hit_count: int = 0
+    exact_norm_hit_count: int = 0
+    definition_hit_count: int = 0
+    parent_context_count: int = 0
+    neighbor_count: int = 0
+    containers: List[str] = field(default_factory=list)
+    sections: List[str] = field(default_factory=list)
+    canonical_refs: List[str] = field(default_factory=list)
+    low_confidence: bool = False
+    negative_recheck_performed: bool = False
+    negative_recheck_added_hits: int = 0
+    reasons: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class AnswerAudit:
+    cited_source_numbers: List[int] = field(default_factory=list)
+    invalid_source_numbers: List[int] = field(default_factory=list)
+    cited_canonical_refs: List[str] = field(default_factory=list)
+    answer_basis: str = "unknown"  # explicit | derived | negative | insufficient | unknown
+    negative_answer_detected: bool = False
+    completeness_warnings: List[str] = field(default_factory=list)
+    citation_warnings: List[str] = field(default_factory=list)
+    auto_fixes: List[str] = field(default_factory=list)
+    recommended_action: str = "accept"  # accept | recheck | clarify | caution
+    confidence: float = 0.5
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class OrchestratorOptions:
+    top_k: int = 8
+    fetch_k: int = 24
+    max_final_results: int = 10
+    max_sources: int = 5
+    include_neighbors: bool = True
+    include_explicit_sections: bool = True
+    # False: das Ranking priorisiert den Hauptvertrag; ein harter Filter machte
+    # Anlagen/Anhänge (Anlage 11, Dienstleistungs-Anhänge) unauffindbar.
+    restrict_to_default_container: bool = False
+    default_container_id: str = "Vertrag"
+    min_score: float | None = None
+    enable_negative_recheck: bool = True
+    enable_clarification: bool = True
+    enable_answer_audit: bool = True
+    enrich_citations_with_canonical_refs: bool = True
+    debug: bool = False
+
+
+@dataclass(slots=True)
+class OrchestratorResult:
+    answer: str
+    answer_type: str
+    hits: List[Dict[str, Any]] = field(default_factory=list)
+    raw_sources: List[Dict[str, Any]] = field(default_factory=list)
+    sources: List[Dict[str, Any]] = field(default_factory=list)
+    analysis: QuestionAnalysis | None = None
+    retrieval_assessment: RetrievalAssessment | None = None
+    answer_audit: AnswerAudit | None = None
+    needs_clarification: bool = False
+    clarification_question: str | None = None
+    debug: Dict[str, Any] = field(default_factory=dict)
+
+    def to_debug_dict(self) -> Dict[str, Any]:
+        return {
+            "analysis": self.analysis.to_dict() if self.analysis else None,
+            "retrieval_assessment": self.retrieval_assessment.to_dict() if self.retrieval_assessment else None,
+            "answer_audit": self.answer_audit.to_dict() if self.answer_audit else None,
+            "needs_clarification": self.needs_clarification,
+            "clarification_question": self.clarification_question,
+            "debug": dict(self.debug),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+def _normalize(text: str) -> str:
+    return " ".join((text or "").strip().split())
+
+
+def _lower(text: str) -> str:
+    return _normalize(text).lower()
+
+
+def _hit_meta(hit: Dict[str, Any]) -> Dict[str, Any]:
+    meta = hit.get("metadata") or {}
+    return meta if isinstance(meta, dict) else {}
+
+
+def _hit_value(hit: Dict[str, Any], *keys: str, default: Any = None) -> Any:
+    meta = _hit_meta(hit)
+    for key in keys:
+        value = hit.get(key)
+        if value is not None and value != "":
+            return value
+    for key in keys:
+        value = meta.get(key)
+        if value is not None and value != "":
+            return value
+    return default
+
+
+def _hit_text(hit: Dict[str, Any]) -> str:
+    return str(hit.get("text") or hit.get("document") or "").strip()
+
+
+def _hit_kinds(hit: Dict[str, Any]) -> List[str]:
+    kinds = hit.get("retrieval_kinds") or []
+    if isinstance(kinds, str):
+        return [kinds]
+    return [str(k) for k in kinds]
+
+
+def _hit_score(hit: Dict[str, Any]) -> float:
+    try:
+        return float(hit.get("rank_score", hit.get("score", 0.0)) or 0.0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _source_key(hit: Dict[str, Any]) -> Tuple[Any, ...]:
+    meta = _hit_meta(hit)
+    text_hash = meta.get("text_hash") or hit.get("text_hash")
+    if text_hash:
+        return ("hash", text_hash)
+    legal_unit_id = meta.get("legal_unit_id") or hit.get("legal_unit_id")
+    if legal_unit_id:
+        return ("legal_unit", legal_unit_id)
+    return (
+        _hit_value(hit, "container", "container_id", default=""),
+        _hit_value(hit, "section", "section_id", default=""),
+        _hit_value(hit, "chunk_index", "chunk_index_in_section", default=""),
+        _hit_text(hit)[:160],
+    )
+
+
+def _canonical_ref_from_hit(hit: Dict[str, Any]) -> str:
+    meta = _hit_meta(hit)
+    direct = _hit_value(hit, "canonical_ref", default=None)
+    if direct:
+        return str(direct)
+
+    paragraph = meta.get("paragraph") or hit.get("paragraph") or _hit_value(hit, "section", "section_id", default="")
+    subsection = meta.get("subsection") or hit.get("subsection")
+    sentence = meta.get("sentence") or hit.get("sentence")
+    number = meta.get("number") or hit.get("number")
+    letter = meta.get("letter") or hit.get("letter")
+
+    parts = [str(paragraph)] if paragraph else []
+    if subsection:
+        parts.append(f"Abs. {subsection}")
+    if sentence:
+        parts.append(f"Satz {sentence}")
+    if number:
+        parts.append(f"Nr. {number}")
+    if letter:
+        parts.append(f"Buchst. {str(letter).lower()}")
+    return " ".join(parts)
+
+
+def _dedupe_hits(hits: Sequence[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    merged: Dict[Tuple[Any, ...], Dict[str, Any]] = {}
+    for hit in hits:
+        key = _source_key(hit)
+        old = merged.get(key)
+        if old is None or _hit_score(hit) > _hit_score(old):
+            merged[key] = dict(hit)
+        else:
+            old_kinds = set(_hit_kinds(old))
+            old_kinds.update(_hit_kinds(hit))
+            old["retrieval_kinds"] = sorted(old_kinds)
+    out = list(merged.values())
+    out.sort(key=lambda h: (_hit_score(h), "parent_context" in set(_hit_kinds(h))), reverse=True)
+    return out
+
+
+def extract_norm_references(question: str, *, max_range: int = 30) -> List[NormReference]:
+    refs: List[NormReference] = []
+    for match in NORM_REF_RE.finditer(question or ""):
+        start = match.group("section")
+        end = match.group("section_to")
+        if end and start.isdigit() and end.isdigit():
+            start_i, end_i = int(start), int(end)
+            if start_i <= end_i and (end_i - start_i) <= max_range:
+                for no in range(start_i, end_i + 1):
+                    refs.append(NormReference(section=str(no)))
+                continue
+        refs.append(
+            NormReference(
+                section=start,
+                section_to=end,
+                subsection=match.group("subsection"),
+                sentence=match.group("sentence"),
+                number=match.group("number"),
+                letter=match.group("letter"),
+            )
+        )
+    seen: set[str] = set()
+    unique: List[NormReference] = []
+    for ref in refs:
+        key = ref.canonical_ref
+        if key not in seen:
+            seen.add(key)
+            unique.append(ref)
+    return unique
+
+
+def expand_query_terms(question: str) -> List[str]:
+    q = _lower(question)
+    terms: List[str] = []
+    for key, values in BUILTIN_QUERY_EXPANSIONS.items():
+        if key in q or any(v.lower() in q for v in values):
+            terms.extend([key, *values])
+    # Extract quoted terms as high-value legal-definition candidates.
+    for quoted in re.findall(r"[„\"']([^„”\"']{2,80})[”\"']", question or ""):
+        terms.append(quoted.strip())
+    return list(dict.fromkeys(t for t in terms if t))
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+class LegalAnswerOrchestrator:
+    """
+    Fachliche Ablaufsteuerung für die juristische RAG-Antwort.
+
+    Diese Klasse ist bewusst unabhängig von FastAPI. `app.py` bleibt die
+    Aussteuerungs- und API-Schicht und kann diesen Orchestrator als einen
+    Knoten im Ask-Graph verwenden.
+
+    Erwartete externe Komponenten:
+    - retriever: besitzt idealerweise `query(...)` und optional `verify_negative_result(...)`
+    - composer: besitzt `compose_with_sources(...)` oder `compose(...)`
+    """
+
+    def __init__(self, retriever: Any, composer: Any, *, options: OrchestratorOptions | None = None):
+        self.retriever = retriever
+        self.composer = composer
+        self.options = options or OrchestratorOptions()
+
+    # ------------------------------------------------------------------
+    # Analysis and planning
+    # ------------------------------------------------------------------
+
+    def analyze_question(self, question: str) -> QuestionAnalysis:
+        q = _normalize(question)
+        lower = q.lower()
+        refs = extract_norm_references(q)
+        expanded = expand_query_terms(q)
+        reasons: List[str] = []
+
+        if is_meta_question(q):
+            intent = "meta"
+            reasons.append("meta_question")
+        elif DEFINITION_RE.search(q):
+            intent = "definition"
+            reasons.append("definition_pattern")
+        elif refs and ENUMERATION_RE.search(q):
+            intent = "norm_enumeration"
+            reasons.append("explicit_norm_and_enumeration_pattern")
+        elif refs:
+            intent = "explicit_norm"
+            reasons.append("explicit_norm_reference")
+        elif COMPARISON_RE.search(q):
+            intent = "comparison"
+            reasons.append("comparison_pattern")
+        elif ENUMERATION_RE.search(q):
+            intent = "enumeration"
+            reasons.append("enumeration_pattern")
+        else:
+            intent = "legal" if classify_question(q) == "legal" else classify_question(q)
+            reasons.append("classified_by_llm_client_rules")
+
+        # Conservative clarification detection: only ask when no explicit norm is
+        # present and the wording is likely underspecified.
+        needs_clarification = False
+        clarification_question: str | None = None
+        if self.options.enable_clarification and not refs and CLARIFICATION_RISK_RE.search(lower):
+            if len(expanded) == 0 and len(q.split()) <= 12:
+                needs_clarification = True
+                clarification_question = (
+                    "Meinst du eine konkrete Regelung im Rahmenvertrag, eine bestimmte Anlage "
+                    "oder die rechtliche Folge für einen bestimmten Sachverhalt?"
+                )
+                reasons.append("underspecified_without_norm_reference")
+
+        return QuestionAnalysis(
+            question=q,
+            question_kind=classify_question(q),
+            intent=intent,
+            norm_references=refs,
+            query_terms=[r.canonical_ref for r in refs],
+            expanded_terms=expanded,
+            needs_clarification=needs_clarification,
+            clarification_question=clarification_question,
+            reasons=reasons,
+        )
+
+    def _retriever_query(self, question: str, analysis: QuestionAnalysis, options: OrchestratorOptions) -> List[Dict[str, Any]]:
+        where = {"container_id": options.default_container_id} if options.restrict_to_default_container else None
+        explicit_sections = [ref.section_id for ref in analysis.norm_references] or None
+
+        kwargs: Dict[str, Any] = {
+            "question": question,
+            "top_k": options.top_k,
+            "where": where,
+            "fetch_k": options.fetch_k,
+            "include_explicit_sections": options.include_explicit_sections,
+            "explicit_sections": explicit_sections,
+            "include_neighbors": options.include_neighbors,
+            "max_final_results": options.max_final_results,
+            "restrict_to_default_container": options.restrict_to_default_container,
+        }
+        if options.min_score is not None:
+            kwargs["min_score"] = options.min_score
+
+        # Newer standalone retriever may accept these flags; older one will not.
+        if analysis.intent == "definition":
+            kwargs["enable_definition_lookup"] = True
+        kwargs["verify_negative_answer"] = False
+
+        try:
+            return list(self.retriever.query(**kwargs) or [])
+        except TypeError:
+            # Backward-compatible fallback for older retrievers.
+            kwargs.pop("enable_definition_lookup", None)
+            kwargs.pop("verify_negative_answer", None)
+            try:
+                return list(self.retriever.query(**kwargs) or [])
+            except TypeError:
+                try:
+                    return list(self.retriever.query(question=question, top_k=options.top_k, where=where) or [])
+                except TypeError:
+                    return list(self.retriever.query(question, top_k=options.top_k) or [])
+
+    def assess_retrieval(self, hits: Sequence[Dict[str, Any]], analysis: QuestionAnalysis) -> RetrievalAssessment:
+        kinds = [kind for hit in hits for kind in _hit_kinds(hit)]
+        containers = list(dict.fromkeys(str(_hit_value(h, "container", "container_id", default="")) for h in hits if _hit_value(h, "container", "container_id", default="")))
+        sections = list(dict.fromkeys(str(_hit_value(h, "section", "section_id", default="")) for h in hits if _hit_value(h, "section", "section_id", default="")))
+        canonical_refs = list(dict.fromkeys(ref for ref in (_canonical_ref_from_hit(h) for h in hits) if ref))
+
+        direct_hit_count = sum(1 for k in kinds if k not in {"neighbor", "parent_context"})
+        exact_count = sum(1 for k in kinds if k in {"exact_norm", "explicit_section", "section_lookup"})
+        definition_count = sum(1 for h in hits if bool(_hit_value(h, "is_definition", default=False)) or "definition" in set(_hit_kinds(h)))
+        parent_count = sum(1 for k in kinds if k == "parent_context")
+        neighbor_count = sum(1 for k in kinds if k == "neighbor")
+
+        low_confidence = False
+        reasons: List[str] = []
+        if not hits:
+            low_confidence = True
+            reasons.append("no_hits")
+        if analysis.norm_references and exact_count == 0:
+            low_confidence = True
+            reasons.append("explicit_norm_without_exact_hit")
+        if analysis.intent == "definition" and definition_count == 0:
+            low_confidence = True
+            reasons.append("definition_question_without_definition_hit")
+        if direct_hit_count == 0 and hits:
+            low_confidence = True
+            reasons.append("only_context_hits")
+
+        return RetrievalAssessment(
+            hit_count=len(hits),
+            direct_hit_count=direct_hit_count,
+            exact_norm_hit_count=exact_count,
+            definition_hit_count=definition_count,
+            parent_context_count=parent_count,
+            neighbor_count=neighbor_count,
+            containers=containers,
+            sections=sections,
+            canonical_refs=canonical_refs[:20],
+            low_confidence=low_confidence,
+            reasons=reasons,
+        )
+
+    def _negative_recheck(
+        self,
+        question: str,
+        analysis: QuestionAnalysis,
+        hits: List[Dict[str, Any]],
+        assessment: RetrievalAssessment,
+        options: OrchestratorOptions,
+    ) -> Tuple[List[Dict[str, Any]], RetrievalAssessment]:
+        if not options.enable_negative_recheck or not assessment.low_confidence:
+            return hits, assessment
+
+        before = len(hits)
+        recheck_hits: List[Dict[str, Any]] = []
+
+        if hasattr(self.retriever, "verify_negative_result"):
+            try:
+                check = self.retriever.verify_negative_result(question)
+                if isinstance(check, dict):
+                    recheck_hits = list(check.get("results") or check.get("hits") or [])
+                elif isinstance(check, list):
+                    recheck_hits = list(check)
+            except TypeError:
+                try:
+                    check = self.retriever.verify_negative_result(question=question)
+                    if isinstance(check, dict):
+                        recheck_hits = list(check.get("results") or check.get("hits") or [])
+                except Exception:
+                    recheck_hits = []
+            except Exception:
+                recheck_hits = []
+
+        if not recheck_hits:
+            # Manual broad fallback: all containers, no restrictive score if possible.
+            broad_options = OrchestratorOptions(**asdict(options))
+            broad_options.restrict_to_default_container = False
+            broad_options.min_score = None
+            broad_options.include_neighbors = True
+            broad_options.include_explicit_sections = True
+            broad_options.fetch_k = max(options.fetch_k, options.top_k * 6)
+            broad_options.max_final_results = max(options.max_final_results, 16)
+            recheck_hits = self._retriever_query(question, analysis, broad_options)
+
+        combined = _dedupe_hits([*hits, *recheck_hits])
+        assessment = self.assess_retrieval(combined, analysis)
+        assessment.negative_recheck_performed = True
+        assessment.negative_recheck_added_hits = max(0, len(combined) - before)
+        if assessment.negative_recheck_added_hits:
+            assessment.reasons.append("negative_recheck_added_hits")
+        return combined, assessment
+
+    # ------------------------------------------------------------------
+    # Composition and audit
+    # ------------------------------------------------------------------
+
+    def _compose(self, question: str, hits: List[Dict[str, Any]], memory: Optional[ConversationMemory]) -> Tuple[str, str, List[Dict[str, Any]]]:
+        if hasattr(self.composer, "compose_with_sources"):
+            try:
+                return self.composer.compose_with_sources(question, hits, memory=memory)
+            except TypeError:
+                pass
+        answer, answer_type = self.composer.compose(question, hits, memory=memory)
+        sources: List[Dict[str, Any]] = []
+        if hasattr(self.composer, "build_sources"):
+            try:
+                sources = self.composer.build_sources(hits)
+            except Exception:
+                sources = []
+        return answer, answer_type, sources
+
+    @staticmethod
+    def _source_numbers_from_source(source: Dict[str, Any], *, fallback: int | None = None) -> List[int]:
+        """Return all source numbers represented by a Composer/API source item."""
+        numbers: List[int] = []
+
+        raw_numbers = source.get("source_numbers")
+        if raw_numbers is not None:
+            if not isinstance(raw_numbers, (list, tuple, set)):
+                raw_numbers = [raw_numbers]
+            for value in raw_numbers:
+                try:
+                    number = int(value)
+                except (TypeError, ValueError):
+                    continue
+                if number not in numbers:
+                    numbers.append(number)
+
+        raw_single = source.get("source_number")
+        if raw_single is not None:
+            try:
+                number = int(raw_single)
+                if number not in numbers:
+                    numbers.append(number)
+            except (TypeError, ValueError):
+                pass
+
+        if not numbers and fallback is not None:
+            numbers.append(fallback)
+
+        return sorted(numbers)
+
+    @staticmethod
+    def _canonical_refs_from_source(source: Dict[str, Any]) -> List[str]:
+        refs: List[str] = []
+
+        raw_refs = source.get("canonical_refs")
+        if raw_refs is not None:
+            if not isinstance(raw_refs, (list, tuple, set)):
+                raw_refs = [raw_refs]
+            for value in raw_refs:
+                ref = _normalize(str(value or ""))
+                if ref and ref not in refs:
+                    refs.append(ref)
+
+        direct = _normalize(str(source.get("canonical_ref") or ""))
+        if direct and direct not in refs:
+            refs.append(direct)
+
+        fallback = _normalize(_canonical_ref_from_hit(source))
+        if fallback and fallback not in refs:
+            refs.append(fallback)
+
+        return refs
+
+    @classmethod
+    def _source_number_to_ref(cls, sources: Sequence[Dict[str, Any]], hits: Sequence[Dict[str, Any]]) -> Dict[int, str]:
+        """Map every visible [Quelle n] number to the best known canonical ref.
+
+        Composer sources may group multiple source numbers into one displayed
+        source item.  The previous implementation only considered
+        ``source_number`` and silently lost grouped numbers such as
+        ``source_numbers=[1, 3]``.
+        """
+        mapping: Dict[int, str] = {}
+
+        for idx, source in enumerate(sources, start=1):
+            numbers = cls._source_numbers_from_source(source, fallback=idx)
+            refs = cls._canonical_refs_from_source(source)
+            if not refs:
+                continue
+
+            # Prefer a concise, stable ref for inline enrichment.  Fine-grained
+            # refs remain available in the separate source list; inline enrichment
+            # must not invent suspicious Buchst.-level citations.
+            ref = refs[0]
+            for candidate in refs:
+                if "Buchst." not in candidate and "Buchstabe" not in candidate:
+                    ref = candidate
+                    break
+
+            for number in numbers:
+                mapping.setdefault(number, ref)
+
+        # Fallback: use retrieval hit order only when Composer sources did not
+        # provide any number mapping.  This keeps older stacks usable while not
+        # overriding Composer numbering.
+        if not mapping:
+            for idx, hit in enumerate(hits, start=1):
+                ref = _canonical_ref_from_hit(hit)
+                if ref:
+                    mapping[idx] = ref
+
+        return mapping
+
+    @staticmethod
+    def _answer_has_inline_ref_after_marker(answer: str, marker_end: int) -> bool:
+        return bool(re.match(r"\s*\(", (answer or "")[marker_end : marker_end + 8]))
+
+    @classmethod
+    def _enrich_answer_citations(cls, answer: str, source_to_ref: Dict[int, str]) -> str:
+        """Conservatively add canonical refs to bare source markers.
+
+        Inline enrichment is intentionally restrained.  Generic section-only
+        references such as ``§ 6`` add little value and caused noisy outputs
+        like ``[Quelle 1] (§ 6) und (§ 6)``.  More specific refs may still be
+        added when the marker is bare and the model did not already provide a
+        parenthetical.
+        """
+        if not answer or not source_to_ref:
+            return answer
+
+        def repl(match: re.Match[str]) -> str:
+            source_no = int(match.group(1))
+            ref = source_to_ref.get(source_no)
+            marker = match.group(0)
+            if not ref:
+                return marker
+            if cls._answer_has_inline_ref_after_marker(answer, match.end()):
+                return marker
+            if not re.search(r"\b(?:Abs\.|Satz|Nr\.|Buchst\.)\b", ref, flags=re.I):
+                return marker
+            return f"{marker} ({ref})"
+
+        return SOURCE_MARKER_RE.sub(repl, answer)
+
+    @staticmethod
+    def _extract_source_numbers(answer: str) -> List[int]:
+        out: List[int] = []
+        for match in SOURCE_MARKER_RE.finditer(answer or ""):
+            try:
+                out.append(int(match.group(1)))
+            except ValueError:
+                continue
+        return list(dict.fromkeys(out))
+
+    @staticmethod
+    def _normalize_legal_ref(ref: str) -> str:
+        s = _normalize(ref)
+        s = re.sub(r"§\s*", "§ ", s)
+        s = re.sub(r"\bAbsatz\b", "Abs.", s, flags=re.I)
+        s = re.sub(r"\bBuchstabe\b|\blit\.", "Buchst.", s, flags=re.I)
+        s = re.sub(r"\s+", " ", s).strip(" .,;:")
+        return s.lower()
+
+    @classmethod
+    def _supported_ref_set(cls, sources: Sequence[Dict[str, Any]], hits: Sequence[Dict[str, Any]]) -> set[str]:
+        refs: set[str] = set()
+        for source in sources:
+            for ref in cls._canonical_refs_from_source(source):
+                refs.add(cls._normalize_legal_ref(ref))
+        for hit in hits:
+            ref = _canonical_ref_from_hit(hit)
+            if ref:
+                refs.add(cls._normalize_legal_ref(ref))
+        return refs
+
+    @classmethod
+    def _downgrade_unsupported_fine_refs(
+        cls,
+        answer: str,
+        sources: Sequence[Dict[str, Any]],
+        hits: Sequence[Dict[str, Any]],
+    ) -> Tuple[str, List[str]]:
+        """Downgrade unsupported Buchst.-level references to Absatz level."""
+        fixes: List[str] = []
+        if not answer:
+            return answer, fixes
+
+        supported = cls._supported_ref_set(sources, hits)
+
+        def repl(match: re.Match[str]) -> str:
+            full = match.group(0)
+            norm_full = cls._normalize_legal_ref(full)
+            if norm_full in supported:
+                return full
+            downgraded = f"§ {match.group('section')} Abs. {match.group('subsection')}"
+            fixes.append(f"downgraded_unsupported_fine_ref:{full}->{downgraded}")
+            return downgraded
+
+        cleaned = FINE_BUCHST_REF_RE.sub(repl, answer)
+
+        # Collapse duplicates introduced by downgrading, e.g.
+        # "[Quelle 1] (§ 6 Abs. 1), § 6 Abs. 1".
+        cleaned = re.sub(
+            r"(\[Quelle\s+\d+(?:[^\]]*)\]\s*\((§\s*\d{1,3}[a-z]?\s+Abs\.\s*\d{1,3}[a-z]?)\))\s*,\s*\2",
+            r"\1",
+            cleaned,
+            flags=re.I,
+        )
+        cleaned = re.sub(
+            r"(\((§\s*\d{1,3}[a-z]?\s+Abs\.\s*\d{1,3}[a-z]?)\))\s*,\s*\2",
+            r"\1",
+            cleaned,
+            flags=re.I,
+        )
+        return cleaned, fixes
+
+    @classmethod
+    def _valid_source_numbers(cls, sources: Sequence[Dict[str, Any]], hits: Sequence[Dict[str, Any]]) -> set[int]:
+        valid: set[int] = set()
+        for idx, source in enumerate(sources, start=1):
+            valid.update(cls._source_numbers_from_source(source, fallback=idx))
+        if not valid:
+            valid.update(range(1, len(hits) + 1))
+        return valid
+
+    @classmethod
+    def _strip_invalid_source_markers_safely(
+        cls,
+        answer: str,
+        sources: Sequence[Dict[str, Any]],
+        hits: Sequence[Dict[str, Any]],
+    ) -> Tuple[str, List[str]]:
+        """Remove invalid source markers including attached parenthetical refs.
+
+        Previous versions removed only ``[Quelle n]`` and left the enrichment
+        tail behind.  That produced broken fragments like ``und (§ 6)``.  This
+        method removes the whole citation atom for invalid markers and then runs
+        a grammar cleanup pass.
+        """
+        fixes: List[str] = []
+        if not answer:
+            return answer, fixes
+
+        valid = cls._valid_source_numbers(sources, hits)
+
+        def repl(match: re.Match[str]) -> str:
+            try:
+                number = int(match.group(1))
+            except (TypeError, ValueError):
+                fixes.append("removed_malformed_source_marker")
+                return ""
+            if number in valid:
+                return match.group(0)
+            fixes.append(f"removed_invalid_source_marker_with_ref:{number}")
+            return ""
+
+        cleaned = SOURCE_MARKER_WITH_OPTIONAL_REF_RE.sub(repl, answer)
+        cleaned = cls._cleanup_citation_grammar(cleaned)
+        return cleaned.strip(), fixes
+
+    @staticmethod
+    def _cleanup_citation_grammar(answer: str) -> str:
+        """Repair grammar after citation cleanup without changing legal content."""
+        cleaned = answer or ""
+
+        # Collapse model/enrichment duplicates such as:
+        #   [Quelle 1] (§ 6), § 6 Abs. 1 -> [Quelle 1] (§ 6 Abs. 1)
+        cleaned = re.sub(
+            r"(\[Quelle\s+\d+(?:[^\]]*)\])\s*\(§\s*(\d{1,3}[a-z]?)\)\s*,\s*(§\s*\2\s+Abs\.\s*\d{1,3}[a-z]?)",
+            r"\1 (\3)",
+            cleaned,
+            flags=re.I,
+        )
+
+        for pattern, replacement in DANGLING_CITATION_GRAMMAR_REPLACEMENTS:
+            cleaned = pattern.sub(replacement, cleaned)
+
+        # Remove duplicate adjacent identical parenthetical legal refs.
+        cleaned = re.sub(
+            r"(\(§[^)]{1,120}\))\s*(?:,|und)\s*\1",
+            r"\1",
+            cleaned,
+            flags=re.I,
+        )
+
+        # Clean common connective leftovers.
+        cleaned = re.sub(r"\s+und\s+([,.;:])", r"\1", cleaned, flags=re.I)
+        cleaned = re.sub(r"\s+und\s*(?=\.)", "", cleaned, flags=re.I)
+        cleaned = re.sub(r"\(\s*\)", "", cleaned)
+        cleaned = re.sub(r"\s+([,.;:])", r"\1", cleaned)
+        cleaned = re.sub(r"[ \t]{2,}", " ", cleaned)
+        cleaned = re.sub(r"\n[ \t]+", "\n", cleaned)
+        return cleaned.strip()
+
+    @classmethod
+    def _ensure_cited_sources_visible(
+        cls,
+        answer: str,
+        sources: List[Dict[str, Any]],
+        hits: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        """Ensure every cited [Quelle n] is represented in returned sources."""
+        cited = cls._extract_source_numbers(answer)
+        if not cited:
+            return sources
+
+        visible = cls._valid_source_numbers(sources, [])
+        missing = [n for n in cited if n not in visible]
+        if not missing:
+            return sources
+
+        out = list(sources)
+        for number in missing:
+            idx = number - 1
+            if 0 <= idx < len(hits):
+                source = dict(hits[idx])
+                source["source_number"] = number
+                source["source_numbers"] = [number]
+                if "canonical_ref" not in source or not source.get("canonical_ref"):
+                    source["canonical_ref"] = _canonical_ref_from_hit(source)
+                out.append(source)
+        return out
+
+    @classmethod
+    def _filter_sources_to_cited_sources(
+        cls,
+        answer: str,
+        sources: List[Dict[str, Any]],
+        hits: List[Dict[str, Any]],
+        *,
+        max_sources: int,
+    ) -> List[Dict[str, Any]]:
+        """Return only sources that are actually cited, with hit fallback.
+
+        For answer quality, visible sources should not include unrelated
+        retrieval leftovers when the answer cites only a small subset.  If the
+        model cites no source markers, keep the curated source list.
+        """
+        cited = cls._extract_source_numbers(answer)
+        if not cited:
+            return list(sources)[:max_sources]
+
+        by_number: Dict[int, Dict[str, Any]] = {}
+        for idx, source in enumerate(sources, start=1):
+            for number in cls._source_numbers_from_source(source, fallback=idx):
+                by_number.setdefault(number, source)
+
+        out: List[Dict[str, Any]] = []
+        seen_ids: set[int] = set()
+        for number in cited:
+            source = by_number.get(number)
+            if source is None:
+                hit_idx = number - 1
+                if 0 <= hit_idx < len(hits):
+                    source = dict(hits[hit_idx])
+                    source["source_number"] = number
+                    source["source_numbers"] = [number]
+                    source.setdefault("canonical_ref", _canonical_ref_from_hit(source))
+            if source is None:
+                continue
+            ident = id(source)
+            if ident in seen_ids:
+                continue
+            seen_ids.add(ident)
+            out.append(source)
+            if len(out) >= max_sources:
+                break
+
+        return out or list(sources)[:max_sources]
+
+    @classmethod
+    def _postprocess_answer(
+        cls,
+        answer: str,
+        sources: List[Dict[str, Any]],
+        hits: List[Dict[str, Any]],
+    ) -> Tuple[str, List[str]]:
+        fixes: List[str] = []
+        cleaned, ref_fixes = cls._downgrade_unsupported_fine_refs(answer, sources, hits)
+        fixes.extend(ref_fixes)
+        cleaned, marker_fixes = cls._strip_invalid_source_markers_safely(cleaned, sources, hits)
+        fixes.extend(marker_fixes)
+        cleaned = cls._cleanup_citation_grammar(cleaned)
+        return cleaned, fixes
+
+    @staticmethod
+    def _detect_answer_basis(answer: str) -> str:
+        a = _lower(answer)
+        if NEGATIVE_ANSWER_RE.search(answer or ""):
+            return "negative"
+        if "ausdrücklich geregelt" in a:
+            return "explicit"
+        if "systematisch" in a or "ableitbar" in a or "auslegung" in a:
+            return "derived"
+        if "nicht belastbar" in a or "keine belastbare" in a:
+            return "insufficient"
+        return "unknown"
+
+    @staticmethod
+    def _expected_list_labels_from_hits(hits: Sequence[Dict[str, Any]]) -> List[str]:
+        text = "\n".join(_hit_text(h) for h in hits[:8])
+        labels = set()
+        for m in re.finditer(r"(?:^|\n|\s)([a-z])\)\s+", text):
+            labels.add(f"{m.group(1).lower()})")
+        for m in re.finditer(r"(?:^|\n|\s)(\d{1,2})[.)]\s+", text):
+            labels.add(f"{m.group(1)}")
+        ordered_letters = [f"{chr(i)})" for i in range(ord("a"), ord("z") + 1) if f"{chr(i)})" in labels]
+        ordered_nums = sorted([x for x in labels if x.isdigit()], key=lambda n: int(n))
+        return ordered_letters + ordered_nums
+
+    def audit_answer(
+        self,
+        question: str,
+        answer: str,
+        hits: List[Dict[str, Any]],
+        sources: List[Dict[str, Any]],
+        analysis: QuestionAnalysis,
+        assessment: RetrievalAssessment,
+    ) -> AnswerAudit:
+        cited = self._extract_source_numbers(answer)
+        valid_numbers = self._valid_source_numbers(sources, hits)
+
+        invalid = [n for n in cited if n not in valid_numbers]
+        basis = self._detect_answer_basis(answer)
+        negative = basis == "negative"
+        completeness_warnings: List[str] = []
+        citation_warnings: List[str] = []
+
+        if not cited and hits and basis != "negative":
+            citation_warnings.append("answer_contains_no_source_markers")
+        if invalid:
+            citation_warnings.append("answer_contains_invalid_source_markers")
+        if analysis.norm_references and not any(ref.section_id in " ".join(assessment.sections + assessment.canonical_refs) for ref in analysis.norm_references):
+            completeness_warnings.append("explicit_norm_not_reflected_in_retrieved_context")
+        if analysis.intent in {"enumeration", "norm_enumeration"}:
+            labels = self._expected_list_labels_from_hits(hits)
+            if len(labels) >= 3:
+                answer_lower = answer.lower()
+                missing_labels = [label for label in labels if label not in answer_lower]
+                # Do not force exact labels in prose answers, but flag likely omissions.
+                if len(missing_labels) >= max(2, len(labels) // 2):
+                    completeness_warnings.append(
+                        "possible_incomplete_enumeration: expected list markers " + ", ".join(labels[:12])
+                    )
+        if negative and assessment.hit_count > 0 and not assessment.low_confidence:
+            completeness_warnings.append("negative_answer_despite_available_context")
+
+        confidence = 0.55
+        if assessment.hit_count:
+            confidence += 0.15
+        if assessment.exact_norm_hit_count and analysis.norm_references:
+            confidence += 0.15
+        if assessment.definition_hit_count and analysis.intent == "definition":
+            confidence += 0.15
+        if citation_warnings:
+            confidence -= 0.15
+        if completeness_warnings:
+            confidence -= 0.15
+        if negative and assessment.low_confidence:
+            confidence -= 0.10
+        confidence = round(max(0.0, min(confidence, 0.98)), 2)
+
+        recommended_action = "accept"
+        if analysis.needs_clarification:
+            recommended_action = "clarify"
+        elif negative and assessment.low_confidence:
+            recommended_action = "recheck"
+        elif citation_warnings or completeness_warnings:
+            recommended_action = "caution"
+
+        refs_by_no = self._source_number_to_ref(sources, hits)
+        cited_refs = [refs_by_no[n] for n in cited if n in refs_by_no]
+
+        return AnswerAudit(
+            cited_source_numbers=cited,
+            invalid_source_numbers=invalid,
+            cited_canonical_refs=cited_refs,
+            answer_basis=basis,
+            negative_answer_detected=negative,
+            completeness_warnings=completeness_warnings,
+            citation_warnings=citation_warnings,
+            recommended_action=recommended_action,
+            confidence=confidence,
+        )
+
+    def _maybe_recompose_after_negative_answer(
+        self,
+        question: str,
+        answer: str,
+        hits: List[Dict[str, Any]],
+        sources: List[Dict[str, Any]],
+        analysis: QuestionAnalysis,
+        assessment: RetrievalAssessment,
+        memory: Optional[ConversationMemory],
+        options: OrchestratorOptions,
+    ) -> Tuple[str, str, List[Dict[str, Any]], List[Dict[str, Any]], RetrievalAssessment]:
+        if not options.enable_negative_recheck or not NEGATIVE_ANSWER_RE.search(answer or ""):
+            return answer, "document", sources, hits, assessment
+
+        old_count = len(hits)
+        hits2, assessment2 = self._negative_recheck(question, analysis, hits, assessment, options)
+        if len(hits2) <= old_count:
+            return answer, "document", sources, hits, assessment2
+
+        answer2, answer_type2, sources2 = self._compose(question, hits2, memory)
+        return answer2, answer_type2, sources2, hits2, assessment2
+
+    # ------------------------------------------------------------------
+    # Public flow
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        question: str,
+        *,
+        memory: Optional[ConversationMemory] = None,
+        options: OrchestratorOptions | None = None,
+    ) -> OrchestratorResult:
+        options = options or self.options
+        question = _normalize(question)
+        analysis = self.analyze_question(question)
+
+        if analysis.intent == "meta":
+            answer, answer_type = self.composer.compose(question, [], memory=memory)
+            return OrchestratorResult(
+                answer=answer,
+                answer_type=answer_type,
+                analysis=analysis,
+                retrieval_assessment=RetrievalAssessment(),
+                answer_audit=AnswerAudit(answer_basis="meta", confidence=1.0),
+            )
+
+        if analysis.needs_clarification:
+            answer = analysis.clarification_question or "Bitte präzisiere deine Frage."
+            return OrchestratorResult(
+                answer=answer,
+                answer_type="clarification",
+                analysis=analysis,
+                retrieval_assessment=RetrievalAssessment(low_confidence=True, reasons=["clarification_required"]),
+                answer_audit=AnswerAudit(answer_basis="clarification", recommended_action="clarify", confidence=0.4),
+                needs_clarification=True,
+                clarification_question=answer,
+            )
+
+        hits = self._retriever_query(question, analysis, options)
+        hits = _dedupe_hits(hits)
+        assessment = self.assess_retrieval(hits, analysis)
+        hits, assessment = self._negative_recheck(question, analysis, hits, assessment, options)
+
+        if not hits:
+            answer = (
+                "Ich habe im verfügbaren Vertragskorpus keine belastbare Textstelle gefunden. "
+                "Das bedeutet nicht zwingend, dass der Sachverhalt rechtlich nicht geregelt ist; "
+                "es heißt zunächst nur, dass die relevante Regelung im aktuellen Retrieval-Kontext "
+                "nicht auffindbar war."
+            )
+            audit = AnswerAudit(
+                answer_basis="insufficient",
+                negative_answer_detected=True,
+                recommended_action="caution",
+                confidence=0.25,
+                completeness_warnings=["no_retrieval_hits_after_recheck"],
+            )
+            return OrchestratorResult(
+                answer=answer,
+                answer_type="none",
+                hits=[],
+                raw_sources=[],
+                sources=[],
+                analysis=analysis,
+                retrieval_assessment=assessment,
+                answer_audit=audit,
+            )
+
+        answer, answer_type, sources = self._compose(question, hits, memory)
+        answer, answer_type, sources, hits, assessment = self._maybe_recompose_after_negative_answer(
+            question, answer, hits, sources, analysis, assessment, memory, options
+        )
+
+        # Keep source visibility and answer postprocessing inside the same
+        # numbering universe as the Composer.  This prevents the API layer from
+        # deleting markers such as [Quelle 3] while the answer still contains
+        # dangling grammar fragments.
+        sources = self._ensure_cited_sources_visible(answer, sources, hits)
+
+        refs_by_no = self._source_number_to_ref(sources, hits)
+        if options.enrich_citations_with_canonical_refs:
+            answer = self._enrich_answer_citations(answer, refs_by_no)
+
+        sources = self._ensure_cited_sources_visible(answer, sources, hits)
+        answer, auto_fixes = self._postprocess_answer(answer, sources, hits)
+        sources = self._ensure_cited_sources_visible(answer, sources, hits)
+        sources = self._filter_sources_to_cited_sources(
+            answer,
+            sources,
+            hits,
+            max_sources=options.max_sources,
+        )
+
+        audit = self.audit_answer(question, answer, hits, sources, analysis, assessment) if options.enable_answer_audit else AnswerAudit()
+        audit.auto_fixes.extend(auto_fixes)
+
+        debug: Dict[str, Any] = {}
+        if options.debug:
+            debug = {
+                "source_number_to_canonical_ref": refs_by_no,
+                "retrieved_hit_count": len(hits),
+                "source_count": len(sources),
+                "answer_auto_fixes": auto_fixes,
+                "returned_source_numbers": [
+                    self._source_numbers_from_source(source, fallback=idx)
+                    for idx, source in enumerate(sources, start=1)
+                ],
+                "cited_source_numbers_after_postprocess": self._extract_source_numbers(answer),
+            }
+
+        return OrchestratorResult(
+            answer=answer,
+            answer_type=answer_type,
+            hits=hits,
+            raw_sources=sources,
+            sources=sources,
+            analysis=analysis,
+            retrieval_assessment=assessment,
+            answer_audit=audit,
+            needs_clarification=False,
+            debug=debug,
+        )

src/retriever.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import logging
+import math
 import re
-from collections import defaultdict
-from typing import Any, Dict, List, Optional, Set, Tuple
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
 
 import chromadb
 from sentence_transformers import SentenceTransformer
@@ -11,26 +13,80 @@ from sentence_transformers import SentenceTransformer
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True, slots=True)
+class NormReference:
+    """Structured representation of a legal reference found in a user question."""
+
+    paragraph: str
+    subsection: str | None = None
+    sentence: str | None = None
+    number: str | None = None
+    letter: str | None = None
+
+    @property
+    def section_id(self) -> str:
+        return self.paragraph
+
+    @property
+    def canonical_ref(self) -> str:
+        parts = [self.paragraph]
+        if self.subsection:
+            parts.append(f"Abs. {self.subsection}")
+        if self.sentence:
+            parts.append(f"Satz {self.sentence}")
+        if self.number:
+            parts.append(f"Nr. {self.number}")
+        if self.letter:
+            parts.append(f"Buchst. {self.letter}")
+        return " ".join(parts)
+
+
 class LegalRetriever:
     """
-    Production-orientierter Retriever für juristische RAG-Anwendungen auf Chroma-Basis.
-
-    Kernziele:
-    - standardmäßig auf den Hauptvertrag filtern,
-    - explizit genannte §§ zusätzlich exakt abrufen,
-    - optional Nachbar-Chunks als Kontext ergänzen,
-    - irrelevante Treffer durch Mindestscore und Section-Limits reduzieren,
-    - Quellen sauber deduplizieren und nicht ungefiltert alle Retrieval-Treffer ausgeben,
-    - beim Start eindeutig zeigen, welche Chroma-DB und Collection verwendet werden.
-
-    Erwartete Metadaten pro Chunk:
-    - container_id, z. B. "Vertrag", "Anlage 4", "Anhang zu Anlage 11"
-    - container_type, z. B. "vertrag", "anlage", "anhang"
-    - section_id, z. B. "§ 6"
+    Standalone production-oriented retriever for legal RAG applications on Chroma.
+
+    This class intentionally does not import from an ingestion package. It can live in a
+    separate backend/chatbot folder and only depends on Chroma metadata produced during
+    ingestion.
+
+    It is backward-compatible with the previous retriever API while adding support for
+    richer legal metadata generated by a parent-child legal chunker.
+
+    Core capabilities:
+    - default filtering to the main contract,
+    - semantic/dense retrieval,
+    - exact norm lookup for § / Abs. / Satz / Nr. / Buchst.,
+    - explicit section lookup for old collections,
+    - definition lookup via is_definition / defined_terms / § 2 fallback,
+    - BM25-like lexical fallback,
+    - optional neighbor chunk expansion,
+    - parent-context expansion via parent_unit_id,
+    - result fusion, deduplication and ranking,
+    - negative-answer verification before saying something is not regulated,
+    - source and context formatting for downstream LLM calls.
+
+    Expected legacy metadata per chunk:
+    - container_id, e.g. "Vertrag", "Anlage 4", "Anhang zu Anlage 11"
+    - container_type, e.g. "vertrag", "anlage", "anhang"
+    - section_id, e.g. "§ 6"
     - section_path
     - page_start, page_end
     - chunk_index_in_section
-    - text_hash optional, aber empfohlen
+    - text_hash optional
+
+    Additional metadata supported from the optimized ingestion/chunking layer:
+    - chunk_kind: "parent" | "child" | ...
+    - legal_unit_id
+    - parent_unit_id
+    - canonical_ref
+    - paragraph
+    - subsection
+    - sentence
+    - number
+    - letter
+    - unit_type
+    - is_definition
+    - defined_terms
     """
 
     SECTION_REF_RE = re.compile(
@@ -39,17 +95,121 @@ class LegalRetriever:
         re.IGNORECASE,
     )
 
+    NORM_REF_RE = re.compile(
+        r"§{1,2}\s*(?P<para>\d+[a-zA-Z]?)"
+        r"(?:\s*(?:Abs\.?|Absatz)\s*(?P<abs>\d+[a-zA-Z]?))?"
+        r"(?:\s*Satz\s*(?P<satz>\d+[a-zA-Z]?))?"
+        r"(?:\s*(?:Nr\.?|Nummer)\s*(?P<nr>\d+[a-zA-Z]?))?"
+        r"(?:\s*(?:Buchst\.?|Buchstabe|lit\.?)\s*(?P<letter>[a-zA-Z]))?",
+        re.IGNORECASE,
+    )
+
+    QUOTED_TERM_RE = re.compile(r"[„\"']([^„“\"']{2,120})[“\"']")
+
+    STOPWORDS = {
+        "aber",
+        "alle",
+        "alles",
+        "als",
+        "also",
+        "am",
+        "an",
+        "auch",
+        "auf",
+        "aus",
+        "bei",
+        "bis",
+        "da",
+        "das",
+        "dass",
+        "dem",
+        "den",
+        "der",
+        "des",
+        "die",
+        "dies",
+        "diese",
+        "dieser",
+        "dieses",
+        "ein",
+        "eine",
+        "einem",
+        "einen",
+        "einer",
+        "eines",
+        "er",
+        "es",
+        "für",
+        "gilt",
+        "hat",
+        "im",
+        "in",
+        "ist",
+        "kann",
+        "mit",
+        "nach",
+        "oder",
+        "rahmenvertrag",
+        "regelt",
+        "sagt",
+        "sind",
+        "unter",
+        "und",
+        "von",
+        "wann",
+        "was",
+        "welche",
+        "welchen",
+        "welcher",
+        "welches",
+        "wenn",
+        "wer",
+        "wie",
+        "wird",
+        "wo",
+        "zum",
+        "zur",
+    }
+
+    QUERY_EXPANSIONS: Dict[str, List[str]] = {
+        "nicht verfügbar": [
+            "nicht lieferbar",
+            "nicht vorrätig",
+            "Lieferengpass",
+            "Verfügbarkeit",
+            "lieferfähig",
+            "lieferbar",
+        ],
+        "nicht lieferbar": ["nicht verfügbar", "Lieferengpass", "lieferfähig", "Verfügbarkeit"],
+        "lieferengpass": ["nicht verfügbar", "nicht lieferbar", "Verfügbarkeit", "lieferfähig"],
+        "auseinzelung": ["Teilmenge", "Auseinzelung", "aus Packungen entnehmen", "§ 16"],
+        "teilmenge": ["Auseinzelung", "Teilmenge", "§ 16"],
+        "beitritt": ["beitreten", "teilnehmen", "Mitgliedsverband", "DAV", "Erklärung", "§ 4"],
+        "teilnahme": ["Beitritt", "teilnehmen", "Mitgliedsverband", "DAV", "§ 4"],
+        "wunscharzneimittel": ["Wunscharzneimittel", "Kostenerstattung", "anderes Fertigarzneimittel", "§ 15"],
+        "pharmazeutische dienstleistungen": ["pharmazeutische Dienstleistung", "Anlage 11", "§ 33"],
+        "biosimilar": ["Biosimilar", "biotechnologisch", "Referenzarzneimittel"],
+        "bioidentical": ["Bioidentical", "Ausgangsstoff", "Herstellungsprozess"],
+        "importarzneimittel": ["Importarzneimittel", "Parallelimport", "Reimport", "Referenzarzneimittel"],
+        "rabattvertrag": ["Rabattvertrag", "rabattbegünstigt", "§ 11", "§ 130a"],
+    }
+
     def __init__(
         self,
         persist_dir: str,
         collection: str,
-        model_name: str,
+        model_name: str = "auto",
         *,
         default_container_id: str = "Vertrag",
         normalize_embeddings: bool = True,
-        default_to_contract: bool = True,
+        default_to_contract: bool = False,
         min_score: float = 0.20,
         verbose_startup: bool = True,
+        lexical_scan_limit: int = 5000,
+        query_prefix: str | None = None,
+        enable_reranker: bool = False,
+        reranker_model: str = "cross-encoder/mmarco-mMiniLMv2-L12-H384-v1",
+        reranker_candidates: int = 20,
     ):
         self.persist_dir = persist_dir
         self.collection_name = collection
@@ -57,29 +217,7 @@ class LegalRetriever:
         self.normalize_embeddings = normalize_embeddings
         self.default_to_contract = default_to_contract
         self.min_score = float(min_score)
-
-        import os
-        from pathlib import Path
-
-        # --- DEBUG: Space-Dateisystem prüfen ---
-        try:
-            print("DEBUG /data exists:", os.path.exists("/data"))
-            if os.path.exists("/data"):
-                print("DEBUG /data listing:", os.listdir("/data")[:50])
-
-            print("DEBUG persist_dir:", persist_dir)
-            print("DEBUG persist_dir exists:", Path(persist_dir).exists())
-            if Path(persist_dir).exists():
-                print("DEBUG persist_dir listing:", [p.name for p in Path(persist_dir).iterdir()][:50])
-                print("DEBUG chroma.sqlite3 exists:", (Path(persist_dir) / "chroma.sqlite3").exists())
-
-            # Optional: falls du vermutest, dass es irgendwo tiefer liegt
-            if os.path.exists("/data"):
-                hits = list(Path("/data").rglob("chroma.sqlite3"))
-                print("DEBUG found chroma.sqlite3 files:", [str(p) for p in hits][:10])
-        except Exception as e:
-            print("DEBUG filesystem check failed:", repr(e))
-        # --- /DEBUG ---
+        self.lexical_scan_limit = int(max(100, lexical_scan_limit))
 
         self.client = chromadb.PersistentClient(path=persist_dir)
 
@@ -93,11 +231,59 @@ class LegalRetriever:
                 f"verfügbare Collections={available!r}"
             ) from exc
 
+        # ------------------------------------------------------------------
+        # Model/collection contract: the ingestion pipeline writes the exact
+        # embedding model and dimension into the collection metadata.  Reading
+        # it here removes the classic failure mode where the query side embeds
+        # with a different model than the index (silently broken ranking or a
+        # hard dimension mismatch deep inside Chroma).
+        # ------------------------------------------------------------------
+        collection_meta = dict(getattr(self.col, "metadata", None) or {})
+        indexed_model = str(collection_meta.get("embedding_model") or "").strip()
+
+        requested = (model_name or "").strip()
+        if not requested or requested.lower() in {"auto", "collection"}:
+            if not indexed_model:
+                raise RuntimeError(
+                    "EMBEDDING_MODEL='auto' verlangt, dass die Collection-Metadata "
+                    "'embedding_model' enthält. Diese Collection wurde offenbar mit "
+                    "einer älteren Ingest-Version gebaut; setze EMBEDDING_MODEL explizit."
+                )
+            model_name = indexed_model
+        elif indexed_model and indexed_model != requested:
+            raise RuntimeError(
+                "Embedding-Modell passt nicht zur Collection: "
+                f"konfiguriert={requested!r}, Collection wurde indexiert mit {indexed_model!r}. "
+                "Entweder EMBEDDING_MODEL='auto' setzen oder die Collection neu ingestieren."
+            )
+
         if verbose_startup:
             self._log_startup_diagnostics()
 
+        self.model_name = model_name
         self.embedder = SentenceTransformer(model_name)
 
+        expected_dim = collection_meta.get("embedding_dim")
+        actual_dim = self.embedder.get_sentence_embedding_dimension()
+        if expected_dim and actual_dim and int(expected_dim) > 0 and int(expected_dim) != int(actual_dim):
+            raise RuntimeError(
+                "Embedding-Dimension passt nicht zur Collection: "
+                f"Modell {model_name!r} liefert {actual_dim}, Collection erwartet {expected_dim}."
+            )
+
+        # E5-style models are trained with asymmetric prefixes.  Their
+        # sentence-transformers configs register EMPTY prompts, so
+        # encode_query() does NOT add the prefix automatically — it must be
+        # applied here.
+        if query_prefix is None:
+            query_prefix = "query: " if "e5" in model_name.lower() else ""
+        self.query_prefix = query_prefix
+
+        self.enable_reranker = bool(enable_reranker)
+        self.reranker_model = reranker_model
+        self.reranker_candidates = int(max(1, reranker_candidates))
+        self._reranker: Any = None
+
     # ------------------------------------------------------------------
     # Diagnostics
     # ------------------------------------------------------------------
@@ -119,10 +305,7 @@ class LegalRetriever:
         )
 
     def diagnostics(self, *, sample: int = 3) -> Dict[str, Any]:
-        """
-        Gibt eine kompakte Laufzeitdiagnose zurück.
-        Nützlich, um alte Collections oder falsche Pfade zu erkennen.
-        """
+        """Return compact runtime diagnostics to catch stale paths or collections."""
         collections = [c.name for c in self.client.list_collections()]
         result: Dict[str, Any] = {
             "persist_dir": self.persist_dir,
@@ -134,7 +317,10 @@ class LegalRetriever:
         try:
             res = self.col.get(limit=sample, include=["metadatas"])
             result["metadata_sample"] = res.get("metadatas", [])
-        except Exception as exc:
+            result["metadata_keys"] = sorted(
+                {key for meta in result["metadata_sample"] if isinstance(meta, dict) for key in meta.keys()}
+            )
+        except Exception as exc:  # noqa: BLE001 - diagnostics must not crash the app.
             result["metadata_sample_error"] = repr(exc)
 
         return result
@@ -145,13 +331,9 @@ class LegalRetriever:
     @staticmethod
     def _build_where(filters: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
         """
-        Baut einen Chroma-konformen where-Filter.
+        Build a Chroma-compatible where filter.
 
-        Chroma erlaubt bei zusammengesetzten Filtern nur einen Top-Level-Operator.
-        Beispiele:
-            {"container_id": "Vertrag"}
-            {"$and": [{"container_id": "Vertrag"}, {"section_id": "§ 6"}]}
-            {"section_id": {"$in": ["§ 6", "§6", "6"]}}
+        Chroma permits only one top-level logical operator for compound filters.
         """
         if not filters:
             return None
@@ -186,6 +368,15 @@ class LegalRetriever:
             return parts[0]
         return {"$and": parts}
 
+    @staticmethod
+    def _where_or(*conditions: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        parts: List[Dict[str, Any]] = [condition for condition in conditions if condition]
+        if not parts:
+            return None
+        if len(parts) == 1:
+            return parts[0]
+        return {"$or": parts}
+
     def _effective_where(
         self,
         where: Optional[Dict[str, Any]],
@@ -193,8 +384,8 @@ class LegalRetriever:
         restrict_to_default_container: Optional[bool],
     ) -> Optional[Dict[str, Any]]:
         """
-        Standard: Suche im Hauptvertrag.
-        Um bewusst in allen Containern zu suchen, query(..., restrict_to_default_container=False) verwenden.
+        By default, search the main contract. To search all containers intentionally,
+        call query(..., restrict_to_default_container=False).
         """
         if where:
             return where
@@ -206,17 +397,13 @@ class LegalRetriever:
         return None
 
     # ------------------------------------------------------------------
-    # Paragraph references
+    # Paragraph and norm references
     # ------------------------------------------------------------------
     @classmethod
     def _parse_section_refs(cls, text: str, *, max_range: int = 30) -> List[str]:
         """
-        Erkennt Paragraphenreferenzen wie:
-            § 6
-            §§ 7-14
-            §§ 7 bis 14
-
-        Gibt normalisierte section_ids wie ["§ 6", "§ 7", ...] zurück.
+        Recognize paragraph references such as § 6, §§ 7-14, §§ 7 bis 14.
+        Returns normalized section_ids such as ["§ 6", "§ 7", ...].
         """
         if not text:
             return []
@@ -240,6 +427,35 @@ class LegalRetriever:
 
         return list(dict.fromkeys(found))
 
+    @classmethod
+    def _parse_norm_refs(cls, text: str) -> List[NormReference]:
+        """Recognize structured references including Abs., Satz, Nr. and Buchst."""
+        if not text:
+            return []
+
+        refs: List[NormReference] = []
+        for match in cls.NORM_REF_RE.finditer(text):
+            para = match.group("para")
+            if not para:
+                continue
+            ref = NormReference(
+                paragraph=f"§ {para}",
+                subsection=match.group("abs"),
+                sentence=match.group("satz"),
+                number=match.group("nr"),
+                letter=(match.group("letter") or "").lower() or None,
+            )
+            refs.append(ref)
+
+        seen: Set[str] = set()
+        unique: List[NormReference] = []
+        for ref in refs:
+            key = ref.canonical_ref.lower()
+            if key not in seen:
+                unique.append(ref)
+                seen.add(key)
+        return unique
+
     @staticmethod
     def _section_variants(section: str) -> List[str]:
         if not section:
@@ -254,6 +470,38 @@ class LegalRetriever:
 
         return list(dict.fromkeys(variants))
 
+    @staticmethod
+    def _paragraph_variants(paragraph: str) -> List[str]:
+        return LegalRetriever._section_variants(paragraph)
+
+    @staticmethod
+    def _subsection_variants(subsection: str | None) -> List[str]:
+        if not subsection:
+            return []
+        s = str(subsection).strip()
+        return list(dict.fromkeys([s, f"Abs. {s}", f"Absatz {s}", f"({s})"]))
+
+    @staticmethod
+    def _sentence_variants(sentence: str | None) -> List[str]:
+        if not sentence:
+            return []
+        s = str(sentence).strip()
+        return list(dict.fromkeys([s, f"Satz {s}"]))
+
+    @staticmethod
+    def _number_variants(number: str | None) -> List[str]:
+        if not number:
+            return []
+        s = str(number).strip()
+        return list(dict.fromkeys([s, f"Nr. {s}", f"Nummer {s}"]))
+
+    @staticmethod
+    def _letter_variants(letter: str | None) -> List[str]:
+        if not letter:
+            return []
+        s = str(letter).strip().lower()
+        return list(dict.fromkeys([s, f"Buchst. {s}", f"Buchstabe {s}", f"{s})"]))
+
     # ------------------------------------------------------------------
     # Public API
     # ------------------------------------------------------------------
@@ -267,21 +515,38 @@ class LegalRetriever:
         include_explicit_sections: bool = True,
         explicit_sections: Optional[List[str]] = None,
         explicit_section_container_ids: Optional[List[str]] = None,
-        max_chunks_per_explicit_section: int = 4,
+        max_chunks_per_explicit_section: int = 6,
+        include_definitions: bool = True,
+        definition_k: int = 8,
+        include_lexical: bool = True,
+        lexical_k: int = 12,
+        lexical_scan_limit: Optional[int] = None,
+        include_parent_context: bool = True,
+        max_parent_contexts: int = 8,
         include_neighbors: bool = True,
         neighbor_window: int = 1,
-        max_final_results: Optional[int] = 10,
+        max_final_results: Optional[int] = 12,
         min_score: Optional[float] = None,
         restrict_to_default_container: Optional[bool] = None,
-        max_chunks_per_section: int = 4,
+        max_chunks_per_section: int = 5,
+        expand_query: bool = True,
+        verify_negative_answer: bool = False,
+        rerank: Optional[bool] = None,
     ) -> List[Dict[str, Any]]:
         """
-        Semantische Suche plus juristische Kontextanreicherung.
-
-        Wichtig:
-        - Wenn `where` nicht gesetzt ist, wird standardmäßig auf `container_id="Vertrag"` gefiltert.
-        - Für eine bewusste Suche über Anlagen/Anhänge hinweg:
-          query(..., restrict_to_default_container=False)
+        Hybrid legal retrieval.
+
+        The old behavior is preserved and expanded:
+        - semantic query,
+        - exact norm/section lookup,
+        - optional neighbors,
+        - section limits.
+
+        New paths:
+        - definitions,
+        - lexical fallback,
+        - parent context expansion,
+        - negative answer verification.
         """
         if not question or not question.strip():
             return []
@@ -290,9 +555,13 @@ class LegalRetriever:
             where,
             restrict_to_default_container=restrict_to_default_container,
         )
-
         threshold = self.min_score if min_score is None else float(min_score)
+        intent = self.classify_query_intent(question)
+        expanded_terms = self.expand_query_terms(question) if expand_query else []
 
+        all_results: List[Dict[str, Any]] = []
+
+        # 1) Semantic dense retrieval.
         semantic_results = self._semantic_query(
             question=question,
             top_k=top_k,
@@ -300,43 +569,290 @@ class LegalRetriever:
             fetch_k=fetch_k,
         )
         semantic_results = [hit for hit in semantic_results if float(hit.get("score", 0.0)) >= threshold]
-
-        all_results: List[Dict[str, Any]] = []
         all_results.extend(semantic_results)
 
-        # Explizit genannte Normen zusätzlich abrufen.
+        # 2) Explicit norm / section lookup.
         if include_explicit_sections:
+            norm_refs = self._parse_norm_refs(question)
             sections = list(explicit_sections or [])
             sections.extend(self._parse_section_refs(question))
             sections = list(dict.fromkeys(sections))
+            containers = explicit_section_container_ids or [self.default_container_id]
+
+            if norm_refs:
+                all_results.extend(
+                    self._get_explicit_norms(
+                        refs=norm_refs,
+                        container_ids=containers,
+                        base_where=effective_where,
+                        max_chunks_per_ref=max_chunks_per_explicit_section,
+                    )
+                )
+            elif sections:
+                all_results.extend(
+                    self._get_explicit_sections(
+                        sections=sections,
+                        container_ids=containers,
+                        base_where=effective_where,
+                        max_chunks_per_section=max_chunks_per_explicit_section,
+                    )
+                )
 
-            if sections:
-                containers = explicit_section_container_ids or [self.default_container_id]
-                exact_results = self._get_explicit_sections(
-                    sections=sections,
-                    container_ids=containers,
+        # 3) Definition lookup for definition-like questions or quoted terms.
+        if include_definitions and (intent == "definition" or self._extract_definition_terms(question)):
+            all_results.extend(
+                self._definition_search(
+                    question=question,
                     base_where=effective_where,
-                    max_chunks_per_section=max_chunks_per_explicit_section,
+                    top_k=definition_k,
+                    expanded_terms=expanded_terms,
                 )
-                all_results.extend(exact_results)
+            )
+
+        # 4) Lexical fallback. This is intentionally independent from embeddings.
+        if include_lexical:
+            all_results.extend(
+                self._lexical_search(
+                    question=question,
+                    base_where=effective_where,
+                    top_k=lexical_k,
+                    expanded_terms=expanded_terms,
+                    scan_limit=lexical_scan_limit or self.lexical_scan_limit,
+                )
+            )
 
-        # Nachbarn nur als Kontext ergänzen.
+        # 5) Neighbor chunks as context. Useful for old collections without parent-child chunks.
         if include_neighbors and neighbor_window > 0:
             neighbor_results: List[Dict[str, Any]] = []
-            for hit in semantic_results[:top_k]:
+            seed_hits = self._dedupe_and_rank(all_results)[: max(top_k, 1)]
+            for hit in seed_hits:
                 neighbor_results.extend(
                     self._get_neighbors(hit, window=neighbor_window, base_where=effective_where)
                 )
             all_results.extend(neighbor_results)
 
-        merged = self._dedupe_and_rank(all_results)
+        # 6) Parent context expansion. Useful for new parent-child legal chunks.
+        if include_parent_context:
+            parent_results = self._expand_parent_context(
+                all_results,
+                base_where=effective_where,
+                max_parent_contexts=max_parent_contexts,
+            )
+            all_results.extend(parent_results)
+
+        merged = self._dedupe_and_rank(all_results, question=question, intent=intent)
+
+        use_reranker = self.enable_reranker if rerank is None else bool(rerank)
+        if use_reranker:
+            merged = self._rerank(question, merged)
+
         merged = self._limit_chunks_per_section(merged, max_chunks_per_section=max_chunks_per_section)
 
         if max_final_results is not None:
             merged = merged[:max_final_results]
 
+        # 7) Optional negative-answer verification. If the normal search returns weak/no results,
+        # run a broad second pass across all containers before the calling layer says "not regulated".
+        if verify_negative_answer and self._looks_like_negative_risk(question, merged):
+            check = self.verify_negative_result(question, max_results=max_final_results or 12)
+            if not check.get("safe_to_answer_negative") and check.get("results"):
+                merged = check["results"]
+
         return merged
 
+    def query_paragraph(
+        self,
+        question: str,
+        paragraph: str,
+        container: str = "Vertrag",
+        top_k: int = 6,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        return self.query(
+            question,
+            top_k=top_k,
+            where={
+                "container_id": container,
+                "section_id": paragraph,
+            },
+            include_explicit_sections=False,
+            **kwargs,
+        )
+
+    def query_anlage(
+        self,
+        question: str,
+        anlage_nr: int,
+        paragraph: Optional[str] = None,
+        top_k: int = 6,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        where: Dict[str, Any] = {"container_id": f"Anlage {anlage_nr}"}
+        if paragraph:
+            where["section_id"] = paragraph
+
+        return self.query(question, top_k=top_k, where=where, **kwargs)
+
+    def query_anhang(
+        self,
+        question: str,
+        anlage_nr: int,
+        top_k: int = 6,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        return self.query(
+            question,
+            top_k=top_k,
+            where={
+                "container_type": "anhang",
+                "container_id": f"Anhang zu Anlage {anlage_nr}",
+            },
+            **kwargs,
+        )
+
+    def get_section(
+        self,
+        section: str,
+        *,
+        container: str = "Vertrag",
+        max_chunks: int = 20,
+        include_parent_context: bool = False,
+    ) -> List[Dict[str, Any]]:
+        variants = self._section_variants(section)
+        where = {"container_id": container, "section_id": {"$in": variants}}
+
+        try:
+            res = self.col.get(where=self._build_where(where), include=["documents", "metadatas"])
+        except Exception:
+            return []
+
+        formatted = self._format_get(res, retrieval_kind="section_lookup", score=1.0)
+        formatted.sort(key=lambda x: x.get("chunk_index", 0))
+        out = formatted[:max_chunks]
+
+        if include_parent_context:
+            out.extend(self._expand_parent_context(out, base_where={"container_id": container}))
+            out = self._dedupe_and_rank(out)
+
+        return out[:max_chunks]
+
+    def verify_negative_result(
+        self,
+        question: str,
+        *,
+        max_results: int = 12,
+        strong_score: float = 0.55,
+    ) -> Dict[str, Any]:
+        """
+        Run a broad second-pass search before the answer layer says that something
+        is not regulated or not found.
+
+        Returns:
+            {
+                "safe_to_answer_negative": bool,
+                "reason": str,
+                "results": list[dict],
+                "strong_result_count": int,
+            }
+        """
+        results = self.query(
+            question,
+            top_k=max(10, max_results),
+            fetch_k=max(40, max_results * 4),
+            include_explicit_sections=True,
+            include_definitions=True,
+            include_lexical=True,
+            lexical_k=max(20, max_results * 2),
+            include_parent_context=True,
+            include_neighbors=True,
+            neighbor_window=1,
+            restrict_to_default_container=False,
+            min_score=0.0,
+            max_final_results=max_results,
+            max_chunks_per_section=6,
+            verify_negative_answer=False,
+        )
+
+        strong_kinds = {"exact_norm", "explicit_section", "definition", "lexical", "parent_context"}
+        strong = [
+            hit
+            for hit in results
+            if float(hit.get("rank_score", hit.get("score", 0.0))) >= strong_score
+            or bool(strong_kinds.intersection(set(hit.get("retrieval_kinds", []))))
+        ]
+
+        if strong:
+            return {
+                "safe_to_answer_negative": False,
+                "reason": "Der breite Kontrollabruf hat potenziell relevante Regelungen gefunden.",
+                "results": results,
+                "strong_result_count": len(strong),
+            }
+
+        return {
+            "safe_to_answer_negative": True,
+            "reason": "Auch der breite Kontrollabruf hat keine belastbaren Treffer gefunden.",
+            "results": results,
+            "strong_result_count": 0,
+        }
+
+    # ------------------------------------------------------------------
+    # Intent and query expansion
+    # ------------------------------------------------------------------
+    @classmethod
+    def classify_query_intent(cls, question: str) -> str:
+        q = cls._norm_text(question)
+        if re.search(r"\b(was\s+versteht|wie\s+definiert|definition|legaldefinition|begriff|bedeutet)\b", q):
+            return "definition"
+        if cls._parse_norm_refs(question):
+            return "norm_lookup"
+        if re.search(r"\b(welche|voraussetzungen|kriterien|tatbestandsmerkmale|nennt|liste|auflistung)\b", q):
+            return "enumeration"
+        if re.search(r"\b(nicht\s+geregelt|keine\s+regelung|steht\s+nicht|nicht\s+enthalten)\b", q):
+            return "negative_check"
+        return "semantic"
+
+    @classmethod
+    def expand_query_terms(cls, question: str) -> List[str]:
+        q = cls._norm_text(question)
+        expansions: List[str] = []
+        for key, values in cls.QUERY_EXPANSIONS.items():
+            if key in q:
+                expansions.extend(values)
+        # Add quoted terms verbatim because legal definition questions often quote exact terms.
+        expansions.extend(cls._extract_definition_terms(question))
+        return list(dict.fromkeys([x.strip() for x in expansions if x and x.strip()]))
+
+    @classmethod
+    def _extract_definition_terms(cls, question: str) -> List[str]:
+        terms: List[str] = []
+        for match in cls.QUOTED_TERM_RE.finditer(question or ""):
+            term = match.group(1).strip()
+            if term:
+                terms.append(term)
+
+        q = (question or "").strip()
+        patterns = [
+            r"unter\s+(.+?)(?:\?|$)",
+            r"begriff\s+(.+?)(?:\?|$)",
+            r"bedeutet\s+(.+?)(?:\?|$)",
+            r"definiert\s+(?:der\s+vertrag\s+|der\s+rahmenvertrag\s+)?(?:ein\s+|eine\s+|einen\s+|das\s+|den\s+|die\s+)?(.+?)(?:\?|$)",
+        ]
+        for pattern in patterns:
+            m = re.search(pattern, q, flags=re.I)
+            if not m:
+                continue
+            raw = m.group(1)
+            raw = re.sub(r"\b(im|in|nach|des|der|die|das|ein|eine|einen|rahmenvertrag|vertrag)\b", " ", raw, flags=re.I)
+            raw = re.sub(r"\s+", " ", raw).strip(" .,:;!?\"'„“")
+            if 2 <= len(raw) <= 80:
+                terms.append(raw)
+
+        return list(dict.fromkeys(terms))
+
+    # ------------------------------------------------------------------
+    # Retrieval paths
+    # ------------------------------------------------------------------
     def _semantic_query(
         self,
         *,
@@ -347,16 +863,14 @@ class LegalRetriever:
     ) -> List[Dict[str, Any]]:
         n_results = fetch_k if fetch_k is not None else max(top_k * 4, top_k)
 
+        query_text = question
+        if self.query_prefix and not question.startswith(self.query_prefix):
+            query_text = f"{self.query_prefix}{question}"
+
         if hasattr(self.embedder, "encode_query"):
-            q_emb = self.embedder.encode_query(
-                [question],
-                normalize_embeddings=self.normalize_embeddings,
-            )[0].tolist()
+            q_emb = self.embedder.encode_query([query_text], normalize_embeddings=self.normalize_embeddings)[0].tolist()
         else:
-            q_emb = self.embedder.encode(
-                [question],
-                normalize_embeddings=self.normalize_embeddings,
-            )[0].tolist()
+            q_emb = self.embedder.encode([query_text], normalize_embeddings=self.normalize_embeddings)[0].tolist()
 
         chroma_where = self._build_where(where)
 
@@ -369,9 +883,58 @@ class LegalRetriever:
 
         return self._format(res, retrieval_kind="semantic")[:n_results]
 
-    # ------------------------------------------------------------------
-    # Explicit section lookup and neighbors
-    # ------------------------------------------------------------------
+    def _get_explicit_norms(
+        self,
+        *,
+        refs: List[NormReference],
+        container_ids: List[str],
+        base_where: Optional[Dict[str, Any]] = None,
+        max_chunks_per_ref: int = 6,
+    ) -> List[Dict[str, Any]]:
+        out: List[Dict[str, Any]] = []
+
+        for container_id in container_ids:
+            for ref in refs:
+                # New metadata path: paragraph / subsection / sentence / number / letter.
+                metadata_filter: Dict[str, Any] = {"container_id": container_id}
+                metadata_filter["paragraph"] = {"$in": self._paragraph_variants(ref.paragraph)}
+                if ref.subsection:
+                    metadata_filter["subsection"] = {"$in": self._subsection_variants(ref.subsection)}
+                if ref.sentence:
+                    metadata_filter["sentence"] = {"$in": self._sentence_variants(ref.sentence)}
+                if ref.number:
+                    metadata_filter["number"] = {"$in": self._number_variants(ref.number)}
+                if ref.letter:
+                    metadata_filter["letter"] = {"$in": self._letter_variants(ref.letter)}
+
+                where = self._where_and(self._build_where(base_where), metadata_filter)
+                formatted: List[Dict[str, Any]] = []
+
+                try:
+                    res = self.col.get(where=where, include=["documents", "metadatas"])
+                    formatted = self._format_get(res, retrieval_kind="exact_norm", score=1.0)
+                except Exception as exc:  # noqa: BLE001 - old collections may not have new metadata fields.
+                    logger.debug("structured exact norm lookup failed", exc_info=exc)
+
+                # Legacy fallback: section_id only, then filter by canonical/text if Abs./Satz/etc. were specified.
+                if not formatted:
+                    formatted = self._get_explicit_sections(
+                        sections=[ref.section_id],
+                        container_ids=[container_id],
+                        base_where=base_where,
+                        max_chunks_per_section=max_chunks_per_ref * 2,
+                        retrieval_kind="exact_norm",
+                    )
+                    if ref.subsection or ref.sentence or ref.number or ref.letter:
+                        narrowed = [hit for hit in formatted if self._hit_matches_norm_ref(hit, ref)]
+                        if narrowed:
+                            formatted = narrowed
+
+                formatted.sort(key=lambda hit: self._exact_norm_sort_key(hit, ref), reverse=True)
+                out.extend(formatted[:max_chunks_per_ref])
+
+        return out
+
     def _get_explicit_sections(
         self,
         *,
@@ -379,6 +942,7 @@ class LegalRetriever:
         container_ids: List[str],
         base_where: Optional[Dict[str, Any]] = None,
         max_chunks_per_section: int = 4,
+        retrieval_kind: str = "explicit_section",
     ) -> List[Dict[str, Any]]:
         out: List[Dict[str, Any]] = []
 
@@ -388,31 +952,124 @@ class LegalRetriever:
 
                 where = self._where_and(
                     self._build_where(base_where),
-                    {
-                        "container_id": container_id,
-                        "section_id": {"$in": variants},
-                    },
+                    {"container_id": container_id, "section_id": {"$in": variants}},
                 )
 
                 try:
-                    res = self.col.get(
-                        where=where,
-                        include=["documents", "metadatas"],
-                    )
-                except Exception as exc:
+                    res = self.col.get(where=where, include=["documents", "metadatas"])
+                except Exception as exc:  # noqa: BLE001
                     logger.debug("explicit section lookup failed", exc_info=exc)
                     continue
 
-                formatted = self._format_get(
-                    res,
-                    retrieval_kind="explicit_section",
-                    score=1.0,
-                )
+                formatted = self._format_get(res, retrieval_kind=retrieval_kind, score=1.0)
                 formatted.sort(key=lambda x: x.get("chunk_index", 0))
                 out.extend(formatted[:max_chunks_per_section])
 
         return out
 
+    def _definition_search(
+        self,
+        *,
+        question: str,
+        base_where: Optional[Dict[str, Any]],
+        top_k: int,
+        expanded_terms: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        terms = self._extract_definition_terms(question)
+        terms.extend(expanded_terms or [])
+        if not terms:
+            terms = self._content_terms(question)[:5]
+
+        terms = list(dict.fromkeys([term for term in terms if term]))
+        candidates: List[Dict[str, Any]] = []
+
+        # Preferred path: new metadata field is_definition=True.
+        where = self._where_and(self._build_where(base_where), {"is_definition": True})
+        try:
+            res = self.col.get(where=where, include=["documents", "metadatas"], limit=self.lexical_scan_limit)
+            candidates.extend(self._format_get(res, retrieval_kind="definition", score=0.85))
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("definition metadata lookup failed", exc_info=exc)
+
+        # Fallback: § 2 usually contains definitions in this contract.
+        if not candidates:
+            containers = [self.default_container_id]
+            candidates.extend(
+                self._get_explicit_sections(
+                    sections=["§ 2"],
+                    container_ids=containers,
+                    base_where=base_where,
+                    max_chunks_per_section=80,
+                    retrieval_kind="definition",
+                )
+            )
+
+        scored: List[Dict[str, Any]] = []
+        for hit in candidates:
+            score = self._definition_score(hit, terms)
+            if score <= 0:
+                continue
+            new_hit = dict(hit)
+            new_hit["score"] = round(min(score, 1.0), 4)
+            new_hit["rank_score"] = new_hit["score"]
+            kinds = set(new_hit.get("retrieval_kinds", []))
+            kinds.add("definition")
+            new_hit["retrieval_kinds"] = sorted(kinds)
+            scored.append(new_hit)
+
+        scored.sort(key=lambda h: (h.get("rank_score", 0.0), h.get("score", 0.0)), reverse=True)
+        return scored[:top_k]
+
+    def _lexical_search(
+        self,
+        *,
+        question: str,
+        base_where: Optional[Dict[str, Any]],
+        top_k: int,
+        expanded_terms: Optional[List[str]] = None,
+        scan_limit: int,
+    ) -> List[Dict[str, Any]]:
+        tokens = self._content_terms(question)
+        phrases = list(expanded_terms or [])
+        for term in self._extract_definition_terms(question):
+            if term not in phrases:
+                phrases.append(term)
+
+        if not tokens and not phrases:
+            return []
+
+        try:
+            res = self.col.get(
+                where=self._build_where(base_where),
+                include=["documents", "metadatas"],
+                limit=max(scan_limit, top_k),
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("lexical scan failed", exc_info=exc)
+            return []
+
+        candidates = self._format_get(res, retrieval_kind="lexical", score=0.0)
+        scored: List[Dict[str, Any]] = []
+        for hit in candidates:
+            score = self._lexical_score(hit, tokens=tokens, phrases=phrases)
+            if score <= 0:
+                continue
+            new_hit = dict(hit)
+            new_hit["score"] = round(score, 4)
+            new_hit["rank_score"] = round(score, 4)
+            new_hit["retrieval_kinds"] = sorted(set(new_hit.get("retrieval_kinds", [])) | {"lexical"})
+            scored.append(new_hit)
+
+        scored.sort(
+            key=lambda hit: (
+                hit.get("rank_score", 0.0),
+                hit.get("score", 0.0),
+                hit.get("metadata", {}).get("is_definition") is True,
+            ),
+            reverse=True,
+        )
+        return scored[:top_k]
+
     def _get_neighbors(
         self,
         hit: Dict[str, Any],
@@ -432,10 +1089,7 @@ class LegalRetriever:
         except (TypeError, ValueError):
             return []
 
-        neighbor_indices = [
-            i for i in range(idx - window, idx + window + 1)
-            if i >= 0 and i != idx
-        ]
+        neighbor_indices = [i for i in range(idx - window, idx + window + 1) if i >= 0 and i != idx]
         if not neighbor_indices:
             return []
 
@@ -449,11 +1103,8 @@ class LegalRetriever:
         )
 
         try:
-            res = self.col.get(
-                where=where,
-                include=["documents", "metadatas"],
-            )
-        except Exception as exc:
+            res = self.col.get(where=where, include=["documents", "metadatas"])
+        except Exception as exc:  # noqa: BLE001
             logger.debug("neighbor lookup failed", exc_info=exc)
             return []
 
@@ -465,94 +1116,100 @@ class LegalRetriever:
         formatted.sort(key=lambda x: x.get("chunk_index", 0))
         return formatted
 
-    # ------------------------------------------------------------------
-    # Convenience wrappers
-    # ------------------------------------------------------------------
-    def query_paragraph(
+    def _expand_parent_context(
         self,
-        question: str,
-        paragraph: str,
-        container: str = "Vertrag",
-        top_k: int = 6,
-        **kwargs: Any,
+        hits: List[Dict[str, Any]],
+        *,
+        base_where: Optional[Dict[str, Any]] = None,
+        max_parent_contexts: int = 8,
     ) -> List[Dict[str, Any]]:
-        return self.query(
-            question,
-            top_k=top_k,
-            where={
-                "container_id": container,
-                "section_id": paragraph,
-            },
-            include_explicit_sections=False,
-            **kwargs,
-        )
+        parent_ids: List[str] = []
+        score_by_parent: Dict[str, float] = defaultdict(float)
 
-    def query_anlage(
-        self,
-        question: str,
-        anlage_nr: int,
-        paragraph: Optional[str] = None,
-        top_k: int = 6,
-        **kwargs: Any,
-    ) -> List[Dict[str, Any]]:
-        where: Dict[str, Any] = {
-            "container_id": f"Anlage {anlage_nr}",
-        }
-        if paragraph:
-            where["section_id"] = paragraph
+        for hit in hits:
+            meta = hit.get("metadata") or {}
+            parent_id = meta.get("parent_unit_id") or meta.get("parent_id")
+            legal_id = meta.get("legal_unit_id")
+            chunk_kind = str(meta.get("chunk_kind") or "").lower()
 
-        return self.query(
-            question,
-            top_k=top_k,
-            where=where,
-            **kwargs,
-        )
+            if not parent_id:
+                continue
+            if legal_id and str(parent_id) == str(legal_id):
+                continue
+            if chunk_kind == "parent":
+                continue
 
-    def query_anhang(
-        self,
-        question: str,
-        anlage_nr: int,
-        top_k: int = 6,
-        **kwargs: Any,
-    ) -> List[Dict[str, Any]]:
-        return self.query(
-            question,
-            top_k=top_k,
-            where={
-                "container_type": "anhang",
-                "container_id": f"Anhang zu Anlage {anlage_nr}",
-            },
-            **kwargs,
-        )
+            parent = str(parent_id)
+            parent_ids.append(parent)
+            score_by_parent[parent] = max(score_by_parent[parent], float(hit.get("rank_score", hit.get("score", 0.0))))
 
-    def get_section(
-        self,
-        section: str,
-        *,
-        container: str = "Vertrag",
-        max_chunks: int = 20,
-    ) -> List[Dict[str, Any]]:
-        variants = self._section_variants(section)
-        where = {
-            "container_id": container,
-            "section_id": {"$in": variants},
-        }
+        parent_ids = list(dict.fromkeys(parent_ids))[:max_parent_contexts]
+        out: List[Dict[str, Any]] = []
 
-        try:
-            res = self.col.get(
-                where=self._build_where(where),
-                include=["documents", "metadatas"],
+        for parent_id in parent_ids:
+            where = self._where_and(
+                self._build_where(base_where),
+                {"legal_unit_id": parent_id},
             )
-        except Exception:
-            return []
+            try:
+                res = self.col.get(where=where, include=["documents", "metadatas"], limit=4)
+            except Exception as exc:  # noqa: BLE001
+                logger.debug("parent context lookup failed", exc_info=exc)
+                continue
 
-        formatted = self._format_get(
-            res,
-            retrieval_kind="section_lookup",
-            score=1.0,
-        )
-        formatted.sort(key=lambda x: x.get("chunk_index", 0))
-        return formatted[:max_chunks]
+            score = min(score_by_parent.get(parent_id, 0.75) + 0.05, 1.0)
+            formatted = self._format_get(res, retrieval_kind="parent_context", score=score)
+            for hit in formatted:
+                hit["retrieval_kinds"] = sorted(set(hit.get("retrieval_kinds", [])) | {"parent_context"})
+            out.extend(formatted)
+
+        return out
+
+    # ------------------------------------------------------------------
+    # Cross-encoder reranking
+    # ------------------------------------------------------------------
+    def _get_reranker(self) -> Any:
+        if self._reranker is None:
+            from sentence_transformers import CrossEncoder
+
+            logger.info("loading cross-encoder reranker", extra={"model": self.reranker_model})
+            self._reranker = CrossEncoder(self.reranker_model, max_length=512)
+        return self._reranker
+
+    def _rerank(self, question: str, hits: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Re-order the fused candidate pool with a cross-encoder.
+
+        The bi-encoder retrieves candidates cheaply; the cross-encoder reads
+        query and passage together and orders them far more precisely.  In the
+        golden evaluation this lifted hybrid retrieval from 17/18 to 18/18 and
+        stabilizes which hit becomes [Quelle 1] for the LLM.
+        """
+        if not hits:
+            return hits
+
+        candidates = hits[: self.reranker_candidates]
+        rest = hits[self.reranker_candidates :]
+        pairs = [(question, str(hit.get("text") or "")) for hit in candidates]
+
+        try:
+            scores = self._get_reranker().predict(pairs, batch_size=16, show_progress_bar=False)
+        except Exception as exc:  # noqa: BLE001 - reranking must never break retrieval.
+            logger.warning("reranker failed; keeping fused order", exc_info=exc)
+            return hits
+
+        reranked: List[Dict[str, Any]] = []
+        for hit, score in zip(candidates, scores):
+            enriched = dict(hit)
+            enriched["rerank_score"] = round(float(score), 4)
+            # Downstream layers (Orchestrator, Composer) sortieren nach
+            # rank_score.  Ohne diese Übernahme würde die Cross-Encoder-Ordnung
+            # dort wieder durch die alte Fusion-Reihenfolge ersetzt.  Sigmoid
+            # bildet die Logits monoton auf (0, 1) ab.
+            enriched["rank_score"] = round(1.0 / (1.0 + math.exp(-float(score))), 4)
+            reranked.append(enriched)
+
+        reranked.sort(key=lambda h: h["rerank_score"], reverse=True)
+        return reranked + rest
 
     # ------------------------------------------------------------------
     # Context and source formatting
@@ -563,10 +1220,9 @@ class LegalRetriever:
         *,
         max_chars: int = 12000,
         include_neighbors: bool = True,
+        include_metadata: bool = True,
     ) -> str:
-        """
-        Baut aus Retriever-Treffern einen stabilen RAG-Kontext für den LLM-Client.
-        """
+        """Build stable RAG context blocks for the downstream LLM client."""
         if not results:
             return ""
 
@@ -578,13 +1234,23 @@ class LegalRetriever:
             if not include_neighbors and kinds == {"neighbor"}:
                 continue
 
+            meta = hit.get("metadata") or {}
+            canonical = meta.get("canonical_ref") or hit.get("canonical_ref") or hit.get("section", "ohne Abschnitt")
+            chunk_kind = meta.get("chunk_kind") or hit.get("chunk_kind") or ""
+            unit_type = meta.get("unit_type") or ""
+            definition = "Definition" if meta.get("is_definition") is True else ""
+            details = ", ".join([x for x in [str(chunk_kind), str(unit_type), definition] if x])
+
             source = (
                 f"[Quelle {i}: {hit.get('container', 'Unbekannt')}::"
-                f"{hit.get('section', 'ohne Abschnitt')}, "
-                f"Seiten {hit.get('page_range', '?')}, "
+                f"{canonical}, Seiten {hit.get('page_range', '?')}, "
                 f"Chunk {hit.get('chunk_index', '?')}, "
-                f"Typ {','.join(hit.get('retrieval_kinds', []))}]"
+                f"Typ {','.join(hit.get('retrieval_kinds', []))}"
             )
+            if include_metadata and details:
+                source += f", Metadaten {details}"
+            source += "]"
+
             text = (hit.get("text") or "").strip()
             block = f"{source}\n{text}"
 
@@ -604,14 +1270,12 @@ class LegalRetriever:
         include_neighbor_only: bool = False,
     ) -> List[Dict[str, Any]]:
         """
-        Baut eine saubere, deduplizierte Quellenliste.
+        Build a clean, deduplicated source list.
 
-        Wichtig:
-        - reine Nachbar-Treffer werden standardmäßig nicht als Hauptquelle angezeigt,
-        - dedupliziert nach Container, Section und Seitenbereich,
-        - begrenzt die Anzahl der angezeigten Quellen.
+        Neighbor-only hits are excluded by default because they are usually context,
+        not the primary legal basis.
         """
-        seen: Set[Tuple[Any, Any, Any]] = set()
+        seen: Set[Tuple[Any, Any, Any, Any]] = set()
         sources: List[Dict[str, Any]] = []
 
         for hit in results:
@@ -619,11 +1283,9 @@ class LegalRetriever:
             if kinds == {"neighbor"} and not include_neighbor_only:
                 continue
 
-            key = (
-                hit.get("container"),
-                hit.get("section"),
-                hit.get("page_range"),
-            )
+            meta = hit.get("metadata") or {}
+            canonical = meta.get("canonical_ref") or hit.get("canonical_ref") or hit.get("section")
+            key = (hit.get("container"), canonical, hit.get("page_range"), meta.get("legal_unit_id"))
 
             if key in seen:
                 continue
@@ -634,6 +1296,7 @@ class LegalRetriever:
                 {
                     "container": hit.get("container"),
                     "section": hit.get("section"),
+                    "canonical_ref": canonical,
                     "path": hit.get("path"),
                     "page_range": hit.get("page_range"),
                     "page_start": hit.get("page_start"),
@@ -641,8 +1304,11 @@ class LegalRetriever:
                     "score": hit.get("score"),
                     "rank_score": hit.get("rank_score"),
                     "retrieval_kinds": hit.get("retrieval_kinds", []),
-                    "canonical_ref": hit.get("metadata", {}).get("canonical_ref"),
-                    "section_title": hit.get("metadata", {}).get("section_title"),
+                    "section_title": meta.get("section_title"),
+                    "chunk_kind": meta.get("chunk_kind"),
+                    "unit_type": meta.get("unit_type"),
+                    "is_definition": meta.get("is_definition"),
+                    "defined_terms": meta.get("defined_terms"),
                 }
             )
 
@@ -652,11 +1318,7 @@ class LegalRetriever:
         return sources
 
     @staticmethod
-    def format_sources_markdown(
-        sources: List[Dict[str, Any]],
-        *,
-        title: str = "Quellen",
-    ) -> str:
+    def format_sources_markdown(sources: List[Dict[str, Any]], *, title: str = "Quellen") -> str:
         if not sources:
             return f"{title}: Keine Quellen gefunden."
 
@@ -666,10 +1328,11 @@ class LegalRetriever:
             section = source.get("section") or "ohne Abschnitt"
             pages = source.get("page_range") or "?"
             canonical = source.get("canonical_ref")
+            label = canonical or section
             if canonical and canonical != section:
                 lines.append(f"- {container}::{section} ({canonical}), Seiten {pages}")
             else:
-                lines.append(f"- {container}::{section}, Seiten {pages}")
+                lines.append(f"- {container}::{label}, Seiten {pages}")
 
         return "\n".join(lines)
 
@@ -696,12 +1359,7 @@ class LegalRetriever:
         return out
 
     @staticmethod
-    def _format_get(
-        res: Dict[str, Any],
-        *,
-        retrieval_kind: str,
-        score: float,
-    ) -> List[Dict[str, Any]]:
+    def _format_get(res: Dict[str, Any], *, retrieval_kind: str, score: float) -> List[Dict[str, Any]]:
         docs = res.get("documents") or []
         metas = res.get("metadatas") or []
 
@@ -720,8 +1378,8 @@ class LegalRetriever:
     @staticmethod
     def _similarity_from_distance(dist: Any) -> float:
         """
-        Für cosine space in Chroma entspricht distance typischerweise 1 - cosine_similarity.
-        Falls eine andere Metrik verwendet wird, bleibt dies nur eine Rangnähe.
+        For cosine space in Chroma, distance is typically 1 - cosine_similarity.
+        For other metrics this remains only an approximate rank signal.
         """
         try:
             similarity = 1.0 - float(dist)
@@ -731,13 +1389,7 @@ class LegalRetriever:
         return round(max(min(similarity, 1.0), -1.0), 4)
 
     @staticmethod
-    def _normalize_hit(
-        *,
-        doc: str,
-        meta: Dict[str, Any],
-        score: float,
-        retrieval_kind: str,
-    ) -> Dict[str, Any]:
+    def _normalize_hit(*, doc: str, meta: Dict[str, Any], score: float, retrieval_kind: str) -> Dict[str, Any]:
         page_start = meta.get("page_start")
         page_end = meta.get("page_end", page_start)
         page_range = "?"
@@ -753,13 +1405,16 @@ class LegalRetriever:
         except (TypeError, ValueError):
             chunk_index = 0
 
+        canonical_ref = meta.get("canonical_ref") or LegalRetriever._canonical_from_metadata(meta) or meta.get("section_id")
+
         hit = {
             "score": round(float(score), 4),
             "rank_score": round(float(score), 4),
             "text": doc or "",
             "container": meta.get("container_id", "Unbekannt"),
             "container_type": meta.get("container_type"),
-            "section": meta.get("section_id", "ohne Abschnitt"),
+            "section": meta.get("section_id") or meta.get("paragraph") or "ohne Abschnitt",
+            "canonical_ref": canonical_ref,
             "path": meta.get("section_path", ""),
             "page_range": page_range,
             "page_start": page_start,
@@ -771,33 +1426,47 @@ class LegalRetriever:
         hit["source_key"] = LegalRetriever._source_key(hit)
         return hit
 
+    @staticmethod
+    def _canonical_from_metadata(meta: Dict[str, Any]) -> str | None:
+        paragraph = meta.get("paragraph") or meta.get("section_id")
+        if not paragraph:
+            return None
+        parts = [str(paragraph)]
+        if meta.get("subsection"):
+            sub = str(meta["subsection"])
+            parts.append(sub if sub.lower().startswith("abs") else f"Abs. {sub}")
+        if meta.get("sentence"):
+            sent = str(meta["sentence"])
+            parts.append(sent if sent.lower().startswith("satz") else f"Satz {sent}")
+        if meta.get("number"):
+            num = str(meta["number"])
+            parts.append(num if num.lower().startswith(("nr", "nummer")) else f"Nr. {num}")
+        if meta.get("letter"):
+            letter = str(meta["letter"]).lower().replace(")", "")
+            parts.append(letter if letter.lower().startswith("buchst") else f"Buchst. {letter}")
+        return " ".join(parts)
+
     @staticmethod
     def _source_key(hit: Dict[str, Any]) -> Tuple[Any, Any, Any, Any]:
         meta = hit.get("metadata") or {}
+        legal_unit_id = meta.get("legal_unit_id")
+        if legal_unit_id:
+            return (hit.get("container"), legal_unit_id, meta.get("chunk_kind"), meta.get("text_hash"))
+
         text_hash = meta.get("text_hash")
         if text_hash:
-            return (
-                hit.get("container"),
-                hit.get("section"),
-                hit.get("chunk_index"),
-                text_hash,
-            )
+            return (hit.get("container"), hit.get("section"), hit.get("chunk_index"), text_hash)
 
-        return (
-            hit.get("container"),
-            hit.get("section"),
-            hit.get("chunk_index"),
-            (hit.get("text") or "")[:120],
-        )
+        return (hit.get("container"), hit.get("section"), hit.get("chunk_index"), (hit.get("text") or "")[:120])
 
     @staticmethod
-    def _dedupe_and_rank(results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """
-        Dedupliziert Treffer und priorisiert:
-        - explizite Normtreffer,
-        - semantische Treffer,
-        - Nachbar-Chunks nur als Zusatzkontext.
-        """
+    def _dedupe_and_rank(
+        results: List[Dict[str, Any]],
+        *,
+        question: str | None = None,
+        intent: str | None = None,
+    ) -> List[Dict[str, Any]]:
+        """Deduplicate hits and rank legal-specific retrieval kinds above generic context."""
         merged: Dict[Tuple[Any, Any, Any, Any], Dict[str, Any]] = {}
 
         for hit in results:
@@ -808,14 +1477,8 @@ class LegalRetriever:
                 merged[key] = dict(hit)
                 continue
 
-            existing["score"] = max(
-                float(existing.get("score", 0.0)),
-                float(hit.get("score", 0.0)),
-            )
-            existing["rank_score"] = max(
-                float(existing.get("rank_score", 0.0)),
-                float(hit.get("rank_score", 0.0)),
-            )
+            existing["score"] = max(float(existing.get("score", 0.0)), float(hit.get("score", 0.0)))
+            existing["rank_score"] = max(float(existing.get("rank_score", 0.0)), float(hit.get("rank_score", 0.0)))
 
             kinds: Set[str] = set(existing.get("retrieval_kinds", []))
             kinds.update(hit.get("retrieval_kinds", []))
@@ -823,27 +1486,56 @@ class LegalRetriever:
 
         ranked = list(merged.values())
 
+        target_refs = LegalRetriever._parse_norm_refs(question or "")
+        target_terms = LegalRetriever._extract_definition_terms(question or "") if question else []
+
         for hit in ranked:
+            meta = hit.get("metadata") or {}
             kinds = set(hit.get("retrieval_kinds", []))
             boost = 0.0
 
+            if "exact_norm" in kinds:
+                boost += 0.16
             if "explicit_section" in kinds or "section_lookup" in kinds:
-                boost += 0.07
+                boost += 0.10
+            if "definition" in kinds:
+                boost += 0.13
+            if "parent_context" in kinds:
+                boost += 0.09
+            if "lexical" in kinds:
+                boost += 0.06
             if "semantic" in kinds:
                 boost += 0.04
             if kinds == {"neighbor"}:
-                boost -= 0.04
+                boost -= 0.05
 
-            # Hauptvertrag leicht bevorzugen.
             if hit.get("container") == "Vertrag":
                 boost += 0.01
 
+            if meta.get("chunk_kind") == "parent":
+                boost += 0.03
+            if meta.get("is_definition") is True and intent == "definition":
+                boost += 0.10
+
+            canonical = str(meta.get("canonical_ref") or hit.get("canonical_ref") or "").lower()
+            for ref in target_refs:
+                if ref.canonical_ref.lower() in canonical or ref.section_id.lower() in canonical:
+                    boost += 0.12
+                    break
+
+            meta_text = LegalRetriever._metadata_text(meta).lower()
+            for term in target_terms:
+                if term.lower() in meta_text:
+                    boost += 0.08
+                    break
+
             hit["rank_score"] = round(float(hit.get("score", 0.0)) + boost, 4)
 
         ranked.sort(
             key=lambda x: (
                 x.get("rank_score", 0.0),
                 x.get("score", 0.0),
+                1 if (x.get("metadata") or {}).get("chunk_kind") == "parent" else 0,
                 -int(x.get("chunk_index", 0)),
             ),
             reverse=True,
@@ -852,11 +1544,7 @@ class LegalRetriever:
         return ranked
 
     @staticmethod
-    def _limit_chunks_per_section(
-        results: List[Dict[str, Any]],
-        *,
-        max_chunks_per_section: int,
-    ) -> List[Dict[str, Any]]:
+    def _limit_chunks_per_section(results: List[Dict[str, Any]], *, max_chunks_per_section: int) -> List[Dict[str, Any]]:
         if max_chunks_per_section <= 0:
             return results
 
@@ -864,10 +1552,166 @@ class LegalRetriever:
         limited: List[Dict[str, Any]] = []
 
         for hit in results:
-            key = (hit.get("container"), hit.get("section"))
+            meta = hit.get("metadata") or {}
+            # Parent chunks are important context; count by canonical parent rather than raw section only.
+            key = (hit.get("container"), hit.get("section"), meta.get("chunk_kind"))
             if counts[key] >= max_chunks_per_section:
                 continue
             counts[key] += 1
             limited.append(hit)
 
         return limited
+
+    # ------------------------------------------------------------------
+    # Scoring helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _hit_matches_norm_ref(hit: Dict[str, Any], ref: NormReference) -> bool:
+        meta = hit.get("metadata") or {}
+        haystack = " ".join(
+            [
+                str(meta.get("canonical_ref") or ""),
+                str(hit.get("canonical_ref") or ""),
+                str(meta.get("paragraph") or ""),
+                str(meta.get("subsection") or ""),
+                str(meta.get("sentence") or ""),
+                str(meta.get("number") or ""),
+                str(meta.get("letter") or ""),
+                hit.get("text") or "",
+            ]
+        ).lower()
+
+        if ref.section_id.lower() not in haystack and ref.section_id.replace(" ", "").lower() not in haystack.replace(" ", ""):
+            return False
+        if ref.subsection and f"abs. {ref.subsection}".lower() not in haystack and f"({ref.subsection})" not in haystack:
+            return False
+        if ref.sentence and f"satz {ref.sentence}".lower() not in haystack:
+            return False
+        if ref.number and f"nr. {ref.number}".lower() not in haystack and f"nummer {ref.number}".lower() not in haystack:
+            return False
+        if ref.letter and f"buchst. {ref.letter}".lower() not in haystack and f"{ref.letter})" not in haystack:
+            return False
+        return True
+
+    @staticmethod
+    def _exact_norm_sort_key(hit: Dict[str, Any], ref: NormReference) -> Tuple[int, int, float, int]:
+        meta = hit.get("metadata") or {}
+        canonical = str(meta.get("canonical_ref") or hit.get("canonical_ref") or "").lower()
+        exact = 1 if ref.canonical_ref.lower() in canonical else 0
+        parent = 1 if str(meta.get("chunk_kind") or "").lower() == "parent" else 0
+        score = float(hit.get("score", 0.0))
+        # Lower chunk index first for paragraph fallbacks.
+        idx = -int(hit.get("chunk_index", 0))
+        return exact, parent, score, idx
+
+    @classmethod
+    def _definition_score(cls, hit: Dict[str, Any], terms: List[str]) -> float:
+        meta = hit.get("metadata") or {}
+        text = f"{hit.get('text') or ''}\n{cls._metadata_text(meta)}"
+        haystack = cls._norm_text(text)
+        score = 0.0
+
+        if meta.get("is_definition") is True:
+            score += 0.45
+        if str(meta.get("unit_type") or "").lower() == "definition":
+            score += 0.35
+        if str(meta.get("section_id") or meta.get("paragraph") or "").replace(" ", "") in {"§2", "2"}:
+            score += 0.12
+
+        for term in terms:
+            t = cls._norm_text(term)
+            if not t:
+                continue
+            if t in haystack:
+                score += 0.35
+            else:
+                token_hits = sum(1 for token in cls._tokenize(t) if token in haystack)
+                if token_hits:
+                    score += min(0.18, 0.06 * token_hits)
+
+        return min(score, 1.0)
+
+    @classmethod
+    def _lexical_score(cls, hit: Dict[str, Any], *, tokens: List[str], phrases: List[str]) -> float:
+        meta = hit.get("metadata") or {}
+        haystack_raw = f"{hit.get('text') or ''}\n{cls._metadata_text(meta)}"
+        haystack = cls._norm_text(haystack_raw)
+        if not haystack:
+            return 0.0
+
+        raw = 0.0
+        token_counts = Counter(cls._tokenize(haystack))
+        for token in tokens:
+            freq = token_counts.get(token, 0)
+            if freq:
+                raw += 1.0 + min(freq - 1, 3) * 0.2
+
+        for phrase in phrases:
+            p = cls._norm_text(phrase)
+            if p and p in haystack:
+                raw += 3.0 if " " in p else 1.4
+
+        # Legal metadata signals.
+        if meta.get("is_definition") is True:
+            raw += 0.5
+        if meta.get("canonical_ref") and any(token in cls._norm_text(str(meta.get("canonical_ref"))) for token in tokens):
+            raw += 0.5
+
+        denom = max(len(tokens) + len(phrases) * 1.5, 4.0)
+        score = raw / denom
+        return round(min(score, 0.99), 4)
+
+    @classmethod
+    def _content_terms(cls, text: str) -> List[str]:
+        tokens = cls._tokenize(cls._norm_text(text))
+        return list(dict.fromkeys([t for t in tokens if len(t) >= 3 and t not in cls.STOPWORDS]))
+
+    @staticmethod
+    def _metadata_text(meta: Dict[str, Any]) -> str:
+        keys = [
+            "canonical_ref",
+            "paragraph",
+            "subsection",
+            "sentence",
+            "number",
+            "letter",
+            "unit_type",
+            "defined_terms",
+            "section_title",
+            "section_id",
+            "section_path",
+            "container_id",
+        ]
+        values: List[str] = []
+        for key in keys:
+            value = meta.get(key)
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple, set)):
+                values.extend(str(v) for v in value)
+            else:
+                values.append(str(value))
+        return " ".join(values)
+
+    @staticmethod
+    def _looks_like_negative_risk(question: str, results: List[Dict[str, Any]]) -> bool:
+        if not results:
+            return True
+        q = LegalRetriever._norm_text(question)
+        if re.search(r"\b(nicht\s+geregelt|keine\s+regelung|steht\s+nicht|nicht\s+enthalten|nicht\s+gefunden)\b", q):
+            return True
+        strongest = max(float(hit.get("rank_score", hit.get("score", 0.0))) for hit in results)
+        return strongest < 0.35
+
+    @staticmethod
+    def _norm_text(text: str) -> str:
+        s = str(text or "").lower()
+        s = s.replace("§§", "§")
+        s = re.sub(r"[\u00a0\t\r\n]+", " ", s)
+        s = re.sub(r"\s+", " ", s)
+        return s.strip()
+
+    @staticmethod
+    def _tokenize(text: str) -> List[str]:
+        return re.findall(r"[a-zäöüß0-9]{2,}", text.lower())
+

src/visualize_graph.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from app import build_ask_workflow
+
+
+OUTPUT_FILE = Path("ask_workflow.png")
+
+
+if __name__ == "__main__":
+    workflow = build_ask_workflow()
+
+    png_bytes = workflow.get_graph(xray=True).draw_mermaid_png()
+    OUTPUT_FILE.write_bytes(png_bytes)
+
+    print(f"PNG generiert: {OUTPUT_FILE.resolve()}")

static/js/script.js

@@ -0,0 +1,745 @@
+const messagesEl = document.getElementById("messages");
+const questionInput = document.getElementById("question");
+const askBtn = document.getElementById("askBtn");
+
+// ----- Helpers -----
+
+function safeText(value, fallback = "") {
+  if (value === null || value === undefined) return fallback;
+  return String(value);
+}
+
+function normalizeArray(value) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function createEl(tag, className, text) {
+  const el = document.createElement(tag);
+  if (className) el.className = className;
+  if (text !== undefined) el.textContent = text;
+  return el;
+}
+
+function scrollToBottom() {
+  window.scrollTo({
+    top: document.body.scrollHeight,
+    behavior: "smooth"
+  });
+}
+
+function setAskLoading(isLoading) {
+  if (!askBtn) return;
+  askBtn.disabled = isLoading;
+  askBtn.textContent = isLoading ? "Antwort wird erstellt …" : "Frage stellen";
+}
+
+// ----- Source rendering -----
+
+function buildSourceMarker(source) {
+  if (source.source_label) return source.source_label;
+  if (source.source_marker) return source.source_marker;
+
+  const numbers = normalizeArray(source.source_numbers)
+    .map(Number)
+    .filter(Number.isFinite)
+    .sort((a, b) => a - b);
+
+  if (numbers.length === 1) {
+    return `[Quelle ${numbers[0]}]`;
+  }
+
+  if (numbers.length > 1) {
+    return `[Quellen ${numbers.join(", ")}]`;
+  }
+
+  if (source.source_number !== null && source.source_number !== undefined) {
+    const n = Number(source.source_number);
+    if (Number.isFinite(n)) return `[Quelle ${n}]`;
+  }
+
+  return "";
+}
+
+function buildCanonicalRefs(source) {
+  const refs = normalizeArray(source.canonical_refs)
+    .map(String)
+    .map(s => s.trim())
+    .filter(Boolean);
+
+  if (refs.length) {
+    return refs.slice(0, 4).join("; ");
+  }
+
+  const singleRef = safeText(source.canonical_ref).trim();
+  const section = safeText(source.section).trim();
+
+  if (singleRef && singleRef !== section) {
+    return singleRef;
+  }
+
+  return "";
+}
+
+function renderSource(source) {
+  // Best case: Backend/Composer already provides a fully curated display title.
+  if (source.display_title) {
+    return safeText(source.display_title);
+  }
+
+  const marker = buildSourceMarker(source);
+
+  const container = safeText(source.container, "Unbekannt").trim();
+  const section = safeText(source.section, "ohne Abschnitt").trim();
+
+  const path =
+    safeText(source.path).trim() ||
+    safeText(source.section_path).trim() ||
+    `${container}::${section}`;
+
+  const pageRange =
+    safeText(source.page_range).trim() ||
+    safeText(source.pages).trim() ||
+    "?";
+
+  const canonicalRefs = buildCanonicalRefs(source);
+  const refPart = canonicalRefs ? ` (${canonicalRefs})` : "";
+
+  const role =
+    Array.isArray(source.retrieval_kinds) &&
+    source.retrieval_kinds.length === 1 &&
+    source.retrieval_kinds[0] === "neighbor"
+      ? " · Kontext/Nachbar"
+      : "";
+
+  return `${marker} ${path}${refPart}, Seiten ${pageRange}${role}`.trim();
+}
+
+function sourceNumbersOf(source) {
+  const numbers = normalizeArray(source.source_numbers)
+    .map(Number)
+    .filter(Number.isFinite);
+
+  const single = Number(source.source_number);
+  if (Number.isFinite(single) && !numbers.includes(single)) {
+    numbers.push(single);
+  }
+
+  return numbers.sort((a, b) => a - b);
+}
+
+function buildSourceNumberMap(sources) {
+  const map = new Map();
+  for (const source of normalizeArray(sources)) {
+    for (const n of sourceNumbersOf(source)) {
+      if (!map.has(n)) map.set(n, source);
+    }
+  }
+  return map;
+}
+
+function isSourceOpenable(source) {
+  return Boolean(source && source.source_file);
+}
+
+function appendSources(parent, sources) {
+  if (!Array.isArray(sources) || sources.length === 0) return;
+
+  const srcWrap = createEl("div", "sources");
+  const strong = createEl("strong", null, "Quellen:");
+  const ul = document.createElement("ul");
+
+  const seen = new Set();
+
+  for (const source of sources) {
+    const rendered = renderSource(source);
+
+    if (!rendered || seen.has(rendered)) continue;
+    seen.add(rendered);
+
+    const li = createEl("li", "source-item");
+
+    if (isSourceOpenable(source)) {
+      const btn = createEl("button", "source-link", rendered);
+      btn.type = "button";
+      btn.title = "Fundstelle im PDF anzeigen";
+      btn.addEventListener("click", () => openSourceInViewer(source));
+
+      const icon = createEl("span", "source-link-icon", "📄");
+      icon.setAttribute("aria-hidden", "true");
+      btn.prepend(icon);
+
+      li.appendChild(btn);
+    } else {
+      li.textContent = rendered;
+    }
+
+    ul.appendChild(li);
+  }
+
+  if (!ul.children.length) return;
+
+  srcWrap.appendChild(strong);
+  srcWrap.appendChild(ul);
+  parent.appendChild(srcWrap);
+}
+
+// ----- Message rendering -----
+
+// Erfasst [Quelle 3], [Quellen 1, 2] usw. – Zusatztext in der Klammer bleibt erhalten.
+const INLINE_MARKER_RE = /\[Quellen?\s+\d+(?:[^\]]*)\]/g;
+
+function renderAnswerText(container, answerText, sources) {
+  const text = safeText(answerText);
+  const bySourceNumber = buildSourceNumberMap(sources);
+
+  let lastIndex = 0;
+
+  for (const match of text.matchAll(INLINE_MARKER_RE)) {
+    if (match.index > lastIndex) {
+      container.appendChild(document.createTextNode(text.slice(lastIndex, match.index)));
+    }
+
+    const marker = match[0];
+    const numbers = (marker.match(/\d+/g) || []).map(Number);
+    const source = numbers.map(n => bySourceNumber.get(n)).find(Boolean);
+
+    if (source && isSourceOpenable(source)) {
+      const btn = createEl("button", "source-ref", marker);
+      btn.type = "button";
+      btn.title = "Fundstelle im PDF anzeigen";
+      btn.addEventListener("click", () => openSourceInViewer(source));
+      container.appendChild(btn);
+    } else {
+      container.appendChild(document.createTextNode(marker));
+    }
+
+    lastIndex = match.index + marker.length;
+  }
+
+  if (lastIndex < text.length) {
+    container.appendChild(document.createTextNode(text.slice(lastIndex)));
+  }
+}
+
+function appendQuestion(text) {
+  const wrap = createEl("div", "msg question");
+  wrap.textContent = "Frage:\n" + safeText(text);
+  messagesEl.appendChild(wrap);
+}
+
+function appendAnswer(answerText, sources) {
+  const wrap = createEl("div", "msg answer");
+
+  const answerDiv = createEl("div", "answer-text");
+  renderAnswerText(answerDiv, answerText, sources);
+
+  wrap.appendChild(answerDiv);
+  appendSources(wrap, sources);
+
+  messagesEl.appendChild(wrap);
+}
+
+function appendError(message) {
+  const wrap = createEl("div", "msg error");
+  wrap.textContent = safeText(message, "Es ist ein Fehler aufgetreten.");
+  messagesEl.appendChild(wrap);
+}
+
+// ----- Ask flow -----
+
+async function send() {
+  const q = questionInput.value.trim();
+  if (!q) return;
+
+  appendQuestion(q);
+  questionInput.value = "";
+  setAskLoading(true);
+
+  try {
+    const res = await fetch("/ask", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ question: q })
+    });
+
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error("Serverantwort war kein gültiges JSON.");
+    }
+
+    if (!res.ok) {
+      throw new Error(data.error || data.detail || `Serverfehler ${res.status}`);
+    }
+
+    appendAnswer(data.answer || "", data.sources || []);
+  } catch (err) {
+    appendError(
+      "Die Anfrage konnte nicht verarbeitet werden.\n" +
+      safeText(err && err.message ? err.message : err)
+    );
+  } finally {
+    setAskLoading(false);
+    scrollToBottom();
+    questionInput.focus();
+  }
+}
+
+// Optional: Enter sendet, Shift+Enter erzeugt Zeilenumbruch.
+questionInput.addEventListener("keydown", event => {
+  if (event.key === "Enter" && !event.shiftKey) {
+    event.preventDefault();
+    send();
+  }
+});
+
+// ----- Prompt Modal -----
+
+const backdrop = document.getElementById("promptModalBackdrop");
+const promptTa = document.getElementById("systemPromptTextarea");
+const promptStatus = document.getElementById("promptStatus");
+
+let defaultPromptCache = "";
+
+function setStatus(msg, ok = true) {
+  promptStatus.style.color = ok ? "#0a6" : "#b00";
+  promptStatus.textContent = msg || "";
+}
+
+function backdropClick(e) {
+  if (e.target === backdrop) {
+    closePromptModal();
+  }
+}
+
+async function openPromptModal() {
+  setStatus("");
+  backdrop.style.display = "flex";
+
+  try {
+    const res = await fetch("/system-prompt");
+    const data = await res.json();
+
+    if (!res.ok) {
+      throw new Error(data.error || data.detail || `Serverfehler ${res.status}`);
+    }
+
+    promptTa.value = data.system_prompt || "";
+    defaultPromptCache = data.default_system_prompt || "";
+  } catch (err) {
+    setStatus("Konnte System-Prompt nicht laden.", false);
+  }
+}
+
+function closePromptModal() {
+  backdrop.style.display = "none";
+  setStatus("");
+}
+
+async function savePrompt() {
+  setStatus("");
+
+  const newPrompt = (promptTa.value || "").trim();
+
+  if (!newPrompt) {
+    setStatus("Prompt ist leer – bitte Text einfügen.", false);
+    return;
+  }
+
+  try {
+    const res = await fetch("/system-prompt", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        system_prompt: newPrompt
+      })
+    });
+
+    const data = await res.json();
+
+    if (!res.ok) {
+      throw new Error(data.error || data.detail || `Serverfehler ${res.status}`);
+    }
+
+    promptTa.value = data.system_prompt || newPrompt;
+    setStatus("Gespeichert.");
+  } catch (err) {
+    setStatus("Speichern fehlgeschlagen.", false);
+  }
+}
+
+async function resetPrompt() {
+  if (!defaultPromptCache) {
+    await openPromptModal();
+  }
+
+  promptTa.value = defaultPromptCache || "";
+  await savePrompt();
+}
+
+// =============================================================================
+// PDF-Fundstellen-Viewer
+//
+// Öffnet das Quell-PDF in einem Side-Panel, springt zur Seite der Fundstelle
+// (page_start aus den Quellen-Metadaten) und hebt den Chunk-Text über den
+// PDF.js-Text-Layer hervor. Das Matching ist bewusst fuzzy (normalisierter
+// Text, satzweise), weil PDF-Extraktion und Ingest-Text leicht abweichen.
+// =============================================================================
+
+const pdfPanel = document.getElementById("pdfPanel");
+const pdfViewportEl = document.getElementById("pdfViewport");
+const pdfPageWrap = document.getElementById("pdfPageWrap");
+const pdfCanvas = document.getElementById("pdfCanvas");
+const pdfTextLayerEl = document.getElementById("pdfTextLayer");
+const pdfStatusEl = document.getElementById("pdfStatus");
+const pdfTitleEl = document.getElementById("pdfPanelTitle");
+const pdfSubtitleEl = document.getElementById("pdfPanelSubtitle");
+const pdfPageIndicator = document.getElementById("pdfPageIndicator");
+const pdfPrevBtn = document.getElementById("pdfPrevBtn");
+const pdfNextBtn = document.getElementById("pdfNextBtn");
+const pdfJumpBtn = document.getElementById("pdfJumpBtn");
+const pdfCloseBtn = document.getElementById("pdfCloseBtn");
+const pdfOpenTab = document.getElementById("pdfOpenTab");
+
+if (window.pdfjsLib) {
+  pdfjsLib.GlobalWorkerOptions.workerSrc =
+    "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";
+}
+
+const pdfState = {
+  doc: null,
+  url: null,
+  pageCount: 0,
+  currentPage: 1,
+  source: null,
+  highlightPages: [],
+  renderSeq: 0
+};
+
+function pdfUrlFor(source) {
+  return "/pdf/" + encodeURIComponent(safeText(source.source_file));
+}
+
+function setPdfStatus(message, isError = false) {
+  pdfStatusEl.textContent = safeText(message);
+  pdfStatusEl.classList.toggle("error", Boolean(isError));
+  pdfStatusEl.style.display = message ? "block" : "none";
+}
+
+function setPdfTitles(source) {
+  const refs = normalizeArray(source.canonical_refs).map(String).filter(Boolean);
+  const ref = refs.length ? refs.slice(0, 3).join("; ") : safeText(source.canonical_ref);
+  const path = safeText(source.path) || safeText(source.section);
+
+  pdfTitleEl.textContent = ref || path || "Fundstelle";
+
+  const parts = [];
+  if (path && path !== ref) parts.push(path);
+  if (source.source_file) parts.push(safeText(source.source_file));
+  const pageInfo = pdfPageRangeLabel(source);
+  if (pageInfo) parts.push(pageInfo);
+  pdfSubtitleEl.textContent = parts.join(" · ");
+}
+
+function pdfPageRangeLabel(source) {
+  const start = Number(source.page_start);
+  const end = Number(source.page_end);
+  if (!Number.isFinite(start)) return "";
+  if (Number.isFinite(end) && end !== start) return `Seiten ${start}–${end}`;
+  return `Seite ${start}`;
+}
+
+function collectHighlightPages(source) {
+  const pages = new Set();
+
+  for (const entry of normalizeArray(source.highlights)) {
+    const start = Number(entry && entry.page_start);
+    const end = Number(entry && entry.page_end);
+    if (Number.isFinite(start)) {
+      const last = Number.isFinite(end) ? end : start;
+      for (let p = start; p <= last && p - start < 20; p++) pages.add(p);
+    }
+  }
+
+  const srcStart = Number(source.page_start);
+  const srcEnd = Number(source.page_end);
+  if (Number.isFinite(srcStart)) {
+    const last = Number.isFinite(srcEnd) ? srcEnd : srcStart;
+    for (let p = srcStart; p <= last && p - srcStart < 20; p++) pages.add(p);
+  }
+
+  return [...pages].sort((a, b) => a - b);
+}
+
+function clampPdfPage(page) {
+  const n = Number(page);
+  if (!Number.isFinite(n)) return 1;
+  return Math.min(Math.max(1, Math.round(n)), pdfState.pageCount || 1);
+}
+
+function openPdfPanel() {
+  pdfPanel.classList.add("open");
+  pdfPanel.setAttribute("aria-hidden", "false");
+}
+
+function closePdfPanel() {
+  pdfPanel.classList.remove("open");
+  pdfPanel.setAttribute("aria-hidden", "true");
+  pdfState.renderSeq++;
+}
+
+function updatePdfNav() {
+  pdfPageIndicator.textContent = pdfState.pageCount
+    ? `Seite ${pdfState.currentPage} / ${pdfState.pageCount}`
+    : "–";
+  pdfPrevBtn.disabled = pdfState.currentPage <= 1;
+  pdfNextBtn.disabled = pdfState.currentPage >= pdfState.pageCount;
+  pdfJumpBtn.style.display = pdfState.highlightPages.length ? "" : "none";
+}
+
+async function openSourceInViewer(source) {
+  if (!source || !source.source_file) return;
+
+  // Fallback ohne PDF.js (z. B. CDN blockiert) oder ohne Panel-Markup
+  // (veraltetes, gecachtes index.html): nativer Browser-Viewer im neuen Tab.
+  if (!window.pdfjsLib || !pdfPanel) {
+    const page = Number(source.page_start);
+    const anchor = Number.isFinite(page) ? `#page=${page}` : "";
+    window.open(pdfUrlFor(source) + anchor, "_blank", "noopener");
+    return;
+  }
+
+  openPdfPanel();
+  setPdfTitles(source);
+
+  const url = pdfUrlFor(source);
+  pdfOpenTab.href = url;
+
+  try {
+    if (!pdfState.doc || pdfState.url !== url) {
+      setPdfStatus("PDF wird geladen …");
+      pdfState.doc = await pdfjsLib.getDocument({ url }).promise;
+      pdfState.url = url;
+      pdfState.pageCount = pdfState.doc.numPages;
+    }
+
+    pdfState.source = source;
+    pdfState.highlightPages = collectHighlightPages(source);
+
+    setPdfStatus("");
+    const target = clampPdfPage(
+      Number.isFinite(Number(source.page_start))
+        ? Number(source.page_start)
+        : (pdfState.highlightPages[0] || 1)
+    );
+    await renderPdfPage(target);
+  } catch (err) {
+    setPdfStatus(
+      "PDF konnte nicht geladen werden: " + safeText(err && err.message ? err.message : err),
+      true
+    );
+  }
+}
+
+async function renderPdfPage(pageNo) {
+  if (!pdfState.doc) return;
+
+  const seq = ++pdfState.renderSeq;
+  pdfState.currentPage = clampPdfPage(pageNo);
+  updatePdfNav();
+
+  const page = await pdfState.doc.getPage(pdfState.currentPage);
+  if (seq !== pdfState.renderSeq) return;
+
+  const availableWidth = Math.max(280, pdfViewportEl.clientWidth - 36);
+  const baseViewport = page.getViewport({ scale: 1 });
+  const scale = Math.min(2.5, availableWidth / baseViewport.width);
+  const viewport = page.getViewport({ scale });
+
+  const outputScale = window.devicePixelRatio || 1;
+  pdfCanvas.width = Math.floor(viewport.width * outputScale);
+  pdfCanvas.height = Math.floor(viewport.height * outputScale);
+  pdfCanvas.style.width = `${viewport.width}px`;
+  pdfCanvas.style.height = `${viewport.height}px`;
+  pdfPageWrap.style.width = `${viewport.width}px`;
+  pdfPageWrap.style.height = `${viewport.height}px`;
+
+  const renderTask = page.render({
+    canvasContext: pdfCanvas.getContext("2d"),
+    viewport,
+    transform: outputScale !== 1 ? [outputScale, 0, 0, outputScale, 0, 0] : null
+  });
+
+  const textContent = await page.getTextContent();
+  await renderTask.promise;
+  if (seq !== pdfState.renderSeq) return;
+
+  pdfTextLayerEl.innerHTML = "";
+  pdfTextLayerEl.style.width = `${viewport.width}px`;
+  pdfTextLayerEl.style.height = `${viewport.height}px`;
+  pdfTextLayerEl.style.setProperty("--scale-factor", String(viewport.scale));
+
+  const textDivs = [];
+  await pdfjsLib.renderTextLayer({
+    textContent,
+    container: pdfTextLayerEl,
+    viewport,
+    textDivs
+  }).promise;
+  if (seq !== pdfState.renderSeq) return;
+
+  const matched = applyPdfHighlights(pdfState.currentPage, textContent.items, textDivs);
+
+  if (matched) {
+    setPdfStatus("");
+    const first = pdfTextLayerEl.querySelector(".pdf-hl");
+    if (first) {
+      first.scrollIntoView({ block: "center", behavior: "smooth" });
+    }
+  } else if (pdfState.highlightPages.includes(pdfState.currentPage)) {
+    setPdfStatus(
+      "Fundstelle liegt auf dieser Seite – die genaue Textstelle konnte nicht automatisch markiert werden."
+    );
+  } else {
+    setPdfStatus("");
+  }
+}
+
+// ----- Text-Matching für die Hervorhebung -----
+
+function pdfNormText(value) {
+  return safeText(value)
+    .toLowerCase()
+    .replace(/­/g, "")
+    .replace(/[^\p{L}\p{N}§]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function pdfSegmentsOf(text) {
+  const out = [];
+  for (const block of safeText(text).split(/\n{2,}/)) {
+    const flat = block.replace(/\s+/g, " ").trim();
+    if (!flat) continue;
+
+    const sentences = flat.split(/(?<=[.;:!?])\s+/);
+    let pushed = false;
+    for (const sentence of sentences) {
+      const s = sentence.trim();
+      if (s.length >= 12) {
+        out.push(s);
+        pushed = true;
+      }
+    }
+    if (!pushed && flat.length >= 12) out.push(flat);
+  }
+  return out;
+}
+
+function applyPdfHighlights(pageNo, items, textDivs) {
+  const source = pdfState.source;
+  if (!source) return false;
+
+  const entries = normalizeArray(source.highlights).filter(entry => {
+    if (!entry || !entry.text) return false;
+    const start = Number(entry.page_start);
+    const end = Number(entry.page_end);
+    if (!Number.isFinite(start)) return true; // ohne Seitenangabe: überall versuchen
+    return pageNo >= start && pageNo <= (Number.isFinite(end) ? end : start);
+  });
+  if (!entries.length) return false;
+
+  // Seitentext mit Index-Map über die Text-Layer-Items aufbauen.
+  // Leere Items (reine Whitespace-Fragmente) dürfen keine zusätzlichen
+  // Leerzeichen erzeugen, sonst scheitert das Substring-Matching.
+  let pageStr = "";
+  const spans = [];
+  items.forEach((item, i) => {
+    const t = pdfNormText(item.str);
+    if (!t) {
+      spans.push({ start: pageStr.length, end: pageStr.length, i });
+      return;
+    }
+    spans.push({ start: pageStr.length, end: pageStr.length + t.length, i });
+    pageStr += t + " ";
+  });
+
+  const markRange = (a, b) => {
+    let any = false;
+    for (const span of spans) {
+      if (span.end <= span.start) continue;
+      if (span.end > a && span.start < b) {
+        const div = textDivs[span.i];
+        if (div && div.textContent.trim()) {
+          div.classList.add("pdf-hl");
+          any = true;
+        }
+      }
+    }
+    return any;
+  };
+
+  let matchedAny = false;
+
+  for (const entry of entries) {
+    for (const segment of pdfSegmentsOf(entry.text)) {
+      const needle = pdfNormText(segment);
+      if (needle.length < 8) continue;
+
+      const idx = pageStr.indexOf(needle);
+      if (idx >= 0) {
+        matchedAny = markRange(idx, idx + needle.length) || matchedAny;
+        continue;
+      }
+
+      // Fallback für längere Segmente: Anfangs-, Mittel- und End-Sonden, damit
+      // Silbentrennung/Extraktionsunterschiede nicht das ganze Segment kosten.
+      if (needle.length > 40) {
+        const mid = Math.floor(needle.length / 2);
+        for (const probe of [needle.slice(0, 40), needle.slice(mid, mid + 40), needle.slice(-40)]) {
+          const trimmed = probe.trim();
+          if (trimmed.length < 16) continue;
+          const j = pageStr.indexOf(trimmed);
+          if (j >= 0) {
+            matchedAny = markRange(j, j + trimmed.length) || matchedAny;
+          }
+        }
+      }
+    }
+  }
+
+  return matchedAny;
+}
+
+// ----- Panel-Bedienung -----
+// Guard: Bei veraltetem, gecachtem index.html fehlen die Panel-Elemente;
+// dann werden keine Listener registriert (openSourceInViewer nutzt den
+// Neuer-Tab-Fallback) und der restliche Chat bleibt voll funktionsfähig.
+
+if (pdfPanel && pdfPrevBtn && pdfNextBtn && pdfJumpBtn && pdfCloseBtn) {
+  pdfPrevBtn.addEventListener("click", () => {
+    if (pdfState.currentPage > 1) renderPdfPage(pdfState.currentPage - 1);
+  });
+
+  pdfNextBtn.addEventListener("click", () => {
+    if (pdfState.currentPage < pdfState.pageCount) renderPdfPage(pdfState.currentPage + 1);
+  });
+
+  pdfJumpBtn.addEventListener("click", () => {
+    if (pdfState.highlightPages.length) renderPdfPage(pdfState.highlightPages[0]);
+  });
+
+  pdfCloseBtn.addEventListener("click", closePdfPanel);
+
+  document.addEventListener("keydown", event => {
+    if (event.key === "Escape" && pdfPanel.classList.contains("open")) {
+      closePdfPanel();
+    }
+  });
+}

static/styles/style.css

@@ -0,0 +1,882 @@
+:root {
+  --bg: #f5f6f8;
+  --surface: rgba(255, 255, 255, 0.72);
+  --surface-strong: rgba(255, 255, 255, 0.88);
+  --surface-soft: rgba(255, 255, 255, 0.52);
+
+  --text: #111827;
+  --text-muted: #6b7280;
+
+  --border: rgba(17, 24, 39, 0.08);
+  --border-light: rgba(255, 255, 255, 0.65);
+
+  --shadow-soft: 0 18px 50px rgba(15, 23, 42, 0.08);
+  --shadow-card: 0 24px 70px rgba(15, 23, 42, 0.10);
+
+  --accent: #111827;
+  --accent-hover: #1f2937;
+
+  --radius-xl: 28px;
+  --radius-lg: 20px;
+  --radius-md: 14px;
+
+  --transition: 180ms ease;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  min-height: 100%;
+  scroll-behavior: smooth;
+}
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  padding: 0;
+  overflow-x: hidden;
+
+  font-family:
+    -apple-system,
+    BlinkMacSystemFont,
+    "SF Pro Display",
+    "SF Pro Text",
+    "Segoe UI",
+    Roboto,
+    Arial,
+    sans-serif;
+
+  color: var(--text);
+
+  background:
+    radial-gradient(circle at 18% 4%, rgba(191, 219, 254, 0.48), transparent 34%),
+    radial-gradient(circle at 84% 3%, rgba(221, 214, 254, 0.42), transparent 32%),
+    radial-gradient(circle at 64% 76%, rgba(207, 250, 254, 0.34), transparent 40%),
+    linear-gradient(180deg, #f8fafc 0%, #f3f6fb 52%, #f7f8fb 100%);
+}
+
+/* Dezentes Premium-Grid */
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+
+  background-image:
+    linear-gradient(rgba(255, 255, 255, 0.30) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.30) 1px, transparent 1px);
+  background-size: 58px 58px;
+
+  opacity: 0.55;
+
+  mask-image: linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, 0.48),
+    rgba(0, 0, 0, 0.28) 45%,
+    transparent 82%
+  );
+}
+
+/* Header */
+
+.header {
+  max-width: 900px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+
+  margin: 30px auto 18px auto;
+  padding: 14px 24px;
+
+  border-radius: 999px;
+
+  background: rgba(255, 255, 255, 0.28);
+  border: 1px solid rgba(255, 255, 255, 0.55);
+
+  box-shadow: 0 14px 44px rgba(15, 23, 42, 0.06);
+
+  backdrop-filter: blur(18px) saturate(140%);
+  -webkit-backdrop-filter: blur(18px) saturate(140%);
+}
+
+.logo {
+  max-height: 72px;
+  width: auto;
+  display: block;
+  background: transparent;
+  filter: drop-shadow(0 8px 18px rgba(15, 23, 42, 0.06));
+}
+
+/* Hauptkarte */
+
+.chat {
+  position: relative;
+
+  width: min(900px, calc(100% - 32px));
+  margin: 28px auto 54px auto;
+  padding: 34px 34px 32px;
+
+  border-radius: var(--radius-xl);
+  border: 1px solid var(--border-light);
+
+  background: rgba(255, 255, 255, 0.72);
+
+  box-shadow: var(--shadow-card);
+
+  backdrop-filter: blur(26px) saturate(150%);
+  -webkit-backdrop-filter: blur(26px) saturate(150%);
+
+  overflow: hidden;
+}
+
+/* Sehr dezenter Lichtverlauf innerhalb der Karte */
+.chat::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+
+  background: linear-gradient(
+    135deg,
+    rgba(255, 255, 255, 0.48),
+    rgba(255, 255, 255, 0.08)
+  );
+}
+
+.chat > * {
+  position: relative;
+  z-index: 1;
+}
+
+h2 {
+  margin: 0 0 24px 0;
+
+  font-size: clamp(1.65rem, 3vw, 2.35rem);
+  line-height: 1.08;
+  letter-spacing: -0.045em;
+  font-weight: 760;
+
+  color: #111827;
+}
+
+h2::after {
+  content: "KI-gestützte juristische Assistenz";
+  display: block;
+
+  margin-top: 10px;
+
+  font-size: 0.92rem;
+  line-height: 1.4;
+  letter-spacing: 0;
+  font-weight: 500;
+
+  color: var(--text-muted);
+}
+
+/* Nachrichten */
+
+.messages {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+
+  margin-bottom: 22px;
+}
+
+.msg {
+  margin-bottom: 0;
+  animation: messageIn 220ms ease both;
+}
+
+.question {
+  align-self: flex-end;
+
+  max-width: 82%;
+  padding: 14px 16px;
+
+  border-radius: 20px 20px 6px 20px;
+
+  color: #ffffff;
+  font-weight: 650;
+  line-height: 1.5;
+  white-space: pre-wrap;
+
+  background: #1f2937;
+
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.16);
+}
+
+.answer {
+  align-self: flex-start;
+
+  max-width: 92%;
+  padding: 17px 18px;
+
+  white-space: pre-wrap;
+  line-height: 1.65;
+
+  border-radius: 20px 20px 20px 6px;
+  border: 1px solid rgba(17, 24, 39, 0.06);
+
+  background: rgba(255, 255, 255, 0.74);
+
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
+
+  backdrop-filter: blur(16px) saturate(140%);
+  -webkit-backdrop-filter: blur(16px) saturate(140%);
+}
+
+/* Eingabe */
+
+textarea {
+  width: 100%;
+  min-height: 104px;
+
+  margin-bottom: 14px;
+  padding: 17px 18px;
+
+  resize: vertical;
+
+  border: 1px solid rgba(17, 24, 39, 0.09);
+  border-radius: 20px;
+  outline: none;
+
+  color: var(--text);
+  font: inherit;
+  line-height: 1.55;
+
+  background: rgba(255, 255, 255, 0.70);
+
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.75),
+    0 10px 28px rgba(15, 23, 42, 0.045);
+
+  backdrop-filter: blur(14px) saturate(135%);
+  -webkit-backdrop-filter: blur(14px) saturate(135%);
+
+  transition:
+    border-color var(--transition),
+    box-shadow var(--transition),
+    background var(--transition);
+}
+
+textarea::placeholder {
+  color: rgba(100, 116, 139, 0.72);
+}
+
+textarea:focus {
+  border-color: rgba(17, 24, 39, 0.18);
+  background: rgba(255, 255, 255, 0.88);
+
+  box-shadow:
+    0 0 0 4px rgba(17, 24, 39, 0.045),
+    0 16px 38px rgba(15, 23, 42, 0.075);
+}
+
+/* Buttons */
+
+.row {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+button {
+  appearance: none;
+
+  border: 0;
+  border-radius: 999px;
+
+  padding: 12px 20px;
+
+  cursor: pointer;
+
+  font: inherit;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+
+  transition:
+    transform var(--transition),
+    box-shadow var(--transition),
+    background var(--transition),
+    color var(--transition),
+    opacity var(--transition);
+}
+
+button:hover {
+  transform: translateY(-1px);
+}
+
+button:active {
+  transform: translateY(0) scale(0.985);
+}
+
+button:focus-visible {
+  outline: 4px solid rgba(17, 24, 39, 0.10);
+  outline-offset: 3px;
+}
+
+#askBtn {
+  color: #ffffff;
+  background: #1f2937;
+  box-shadow: 0 14px 30px rgba(15, 23, 42, 0.18);
+}
+
+#askBtn:hover {
+  background: #111827;
+  box-shadow: 0 18px 36px rgba(15, 23, 42, 0.22);
+}
+
+#promptBtn,
+.modal-actions button {
+  color: #111827;
+
+  background: rgba(255, 255, 255, 0.68);
+
+  border: 1px solid rgba(17, 24, 39, 0.075);
+
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.78),
+    0 10px 24px rgba(15, 23, 42, 0.055);
+
+  backdrop-filter: blur(14px) saturate(135%);
+  -webkit-backdrop-filter: blur(14px) saturate(135%);
+}
+
+#promptBtn:hover,
+.modal-actions button:hover {
+  background: rgba(255, 255, 255, 0.86);
+
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.86),
+    0 14px 30px rgba(15, 23, 42, 0.08);
+}
+
+/* Quellen */
+
+.sources {
+  margin-top: 14px;
+  padding-top: 12px;
+
+  font-size: 0.9em;
+  color: var(--text-muted);
+
+  border-top: 1px solid rgba(17, 24, 39, 0.075);
+}
+
+.sources strong {
+  color: #374151;
+}
+
+.sources ul {
+  margin: 8px 0 0 18px;
+  padding: 0;
+}
+
+.sources li {
+  margin: 4px 0;
+}
+
+/* Klickbare Quellen */
+
+.source-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+
+  width: auto;
+  padding: 6px 12px;
+
+  border: 1px solid rgba(17, 24, 39, 0.10);
+  border-radius: 12px;
+
+  font: inherit;
+  font-size: 1em;
+  font-weight: 500;
+  text-align: left;
+  color: #1d4ed8;
+
+  background: rgba(255, 255, 255, 0.55);
+  box-shadow: none;
+
+  cursor: pointer;
+}
+
+.source-link:hover {
+  color: #1e40af;
+  border-color: rgba(29, 78, 216, 0.35);
+  background: rgba(219, 234, 254, 0.55);
+  transform: none;
+}
+
+.source-link-icon {
+  flex: none;
+  font-size: 0.95em;
+}
+
+/* Inline-Quellenmarker im Antworttext */
+
+.source-ref {
+  display: inline;
+  padding: 1px 6px;
+  margin: 0 1px;
+
+  border: 1px solid rgba(29, 78, 216, 0.22);
+  border-radius: 8px;
+
+  font: inherit;
+  font-size: 0.88em;
+  font-weight: 600;
+  color: #1d4ed8;
+
+  background: rgba(219, 234, 254, 0.45);
+  box-shadow: none;
+
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.source-ref:hover {
+  color: #1e40af;
+  background: rgba(191, 219, 254, 0.75);
+  border-color: rgba(29, 78, 216, 0.45);
+  transform: none;
+}
+
+/* PDF-Fundstellen-Viewer (Side-Panel) */
+
+.pdf-panel {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+
+  width: min(760px, 100vw);
+
+  display: flex;
+  flex-direction: column;
+
+  z-index: 9000;
+
+  border-left: 1px solid rgba(255, 255, 255, 0.65);
+
+  background: rgba(248, 250, 252, 0.92);
+
+  box-shadow: -24px 0 70px rgba(15, 23, 42, 0.22);
+
+  backdrop-filter: blur(26px) saturate(150%);
+  -webkit-backdrop-filter: blur(26px) saturate(150%);
+
+  transform: translateX(105%);
+  transition: transform 260ms ease;
+}
+
+.pdf-panel.open {
+  transform: translateX(0);
+}
+
+.pdf-panel-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+
+  padding: 14px 18px;
+
+  border-bottom: 1px solid rgba(17, 24, 39, 0.08);
+
+  background: rgba(255, 255, 255, 0.66);
+}
+
+.pdf-panel-titles {
+  min-width: 0;
+}
+
+.pdf-panel-title {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  color: #111827;
+
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.pdf-panel-subtitle {
+  margin-top: 2px;
+
+  font-size: 0.82em;
+  color: var(--text-muted);
+
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.pdf-panel-controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: none;
+}
+
+.pdf-ctrl {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  min-width: 34px;
+  height: 34px;
+  padding: 0 10px;
+
+  border: 1px solid rgba(17, 24, 39, 0.10);
+  border-radius: 10px;
+
+  font: inherit;
+  font-size: 0.95em;
+  font-weight: 600;
+  color: #111827;
+  text-decoration: none;
+
+  background: rgba(255, 255, 255, 0.72);
+  box-shadow: none;
+
+  cursor: pointer;
+}
+
+.pdf-ctrl:hover {
+  background: rgba(255, 255, 255, 0.95);
+  transform: none;
+}
+
+.pdf-ctrl:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.pdf-jump {
+  color: #92400e;
+  border-color: rgba(217, 119, 6, 0.35);
+  background: rgba(254, 243, 199, 0.75);
+}
+
+.pdf-jump:hover {
+  background: rgba(253, 230, 138, 0.9);
+}
+
+.pdf-close {
+  font-size: 1.25em;
+}
+
+.pdf-page-indicator {
+  padding: 0 4px;
+
+  font-size: 0.85em;
+  font-weight: 600;
+  color: var(--text-muted);
+
+  white-space: nowrap;
+}
+
+.pdf-viewport {
+  flex: 1;
+  overflow: auto;
+
+  padding: 18px;
+}
+
+.pdf-status {
+  display: none;
+
+  margin: 0 auto 12px auto;
+  padding: 10px 14px;
+
+  max-width: 640px;
+
+  border: 1px solid rgba(217, 119, 6, 0.25);
+  border-radius: 12px;
+
+  font-size: 0.88em;
+  color: #92400e;
+
+  background: rgba(254, 243, 199, 0.8);
+}
+
+.pdf-status.error {
+  color: #b91c1c;
+  border-color: rgba(185, 28, 28, 0.25);
+  background: rgba(254, 226, 226, 0.85);
+}
+
+.pdf-page-wrap {
+  position: relative;
+  margin: 0 auto;
+
+  background: #ffffff;
+
+  box-shadow: 0 14px 44px rgba(15, 23, 42, 0.16);
+  border-radius: 4px;
+}
+
+.pdf-page-wrap canvas {
+  display: block;
+  border-radius: 4px;
+}
+
+/* PDF.js-Text-Layer (unsichtbarer, selektierbarer Text über dem Canvas) */
+
+.textLayer {
+  position: absolute;
+  inset: 0;
+
+  overflow: hidden;
+
+  line-height: 1;
+  text-align: initial;
+
+  forced-color-adjust: none;
+}
+
+.textLayer span,
+.textLayer br {
+  position: absolute;
+
+  color: transparent;
+  white-space: pre;
+
+  cursor: text;
+
+  transform-origin: 0% 0%;
+}
+
+/* Hervorhebung der Fundstelle */
+
+.textLayer span.pdf-hl {
+  background: rgba(255, 213, 64, 0.85);
+  mix-blend-mode: multiply;
+
+  border-radius: 3px;
+  box-shadow: 0 0 0 2px rgba(255, 213, 64, 0.85);
+}
+
+/* Modal */
+
+.modal-backdrop {
+  position: fixed;
+  inset: 0;
+
+  display: none;
+  align-items: center;
+  justify-content: center;
+
+  padding: 24px;
+
+  z-index: 9999;
+
+  background: rgba(15, 23, 42, 0.34);
+
+  backdrop-filter: blur(14px) saturate(140%);
+  -webkit-backdrop-filter: blur(14px) saturate(140%);
+
+  animation: fadeIn 180ms ease both;
+}
+
+.modal {
+  width: min(900px, 100%);
+
+  padding: 24px;
+
+  border-radius: var(--radius-xl);
+  border: 1px solid rgba(255, 255, 255, 0.68);
+
+  background: rgba(255, 255, 255, 0.82);
+
+  box-shadow: 0 30px 90px rgba(15, 23, 42, 0.22);
+
+  backdrop-filter: blur(28px) saturate(150%);
+  -webkit-backdrop-filter: blur(28px) saturate(150%);
+
+  animation: modalIn 220ms ease both;
+}
+
+.modal h3 {
+  margin: 0 0 14px 0;
+
+  font-size: 1.35rem;
+  letter-spacing: -0.035em;
+
+  color: #111827;
+}
+
+.modal textarea {
+  min-height: 180px;
+  margin-bottom: 14px;
+  font-family: inherit;
+}
+
+.modal-actions {
+  display: flex;
+  gap: 10px;
+  justify-content: flex-end;
+  flex-wrap: wrap;
+}
+
+.hint {
+  margin-top: 12px;
+
+  font-size: 0.9em;
+  line-height: 1.5;
+
+  color: var(--text-muted);
+}
+
+.status {
+  min-height: 1.2em;
+
+  margin-right: auto;
+
+  align-self: center;
+
+  font-size: 0.9em;
+  font-weight: 600;
+
+  color: #059669;
+}
+
+/* Scrollbar */
+
+::-webkit-scrollbar {
+  width: 12px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(15, 23, 42, 0.16);
+  border: 4px solid transparent;
+  border-radius: 999px;
+  background-clip: content-box;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(15, 23, 42, 0.25);
+  border: 4px solid transparent;
+  background-clip: content-box;
+}
+
+/* Animationen */
+
+@keyframes messageIn {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes modalIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px) scale(0.98);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+/* Responsive */
+
+@media (max-width: 720px) {
+  .header {
+    width: min(100% - 20px, 900px);
+    margin-top: 18px;
+    padding: 14px 18px;
+  }
+
+  .logo {
+    max-height: 58px;
+  }
+
+  .chat {
+    width: min(100% - 20px, 900px);
+    margin: 18px auto 28px auto;
+    padding: 22px;
+    border-radius: 24px;
+  }
+
+  .question,
+  .answer {
+    max-width: 100%;
+  }
+
+  .row {
+    align-items: stretch;
+  }
+
+  button {
+    width: 100%;
+  }
+
+  .modal {
+    padding: 20px;
+    border-radius: 24px;
+  }
+
+  .modal-actions {
+    flex-direction: column;
+  }
+
+  .status {
+    margin-right: 0;
+  }
+
+  /* Viewer-Bedienelemente behalten ihre kompakte Breite */
+  .pdf-ctrl,
+  .source-ref,
+  .source-link {
+    width: auto;
+  }
+
+  .pdf-panel {
+    width: 100vw;
+  }
+
+  .pdf-panel-header {
+    flex-wrap: wrap;
+  }
+
+  .pdf-viewport {
+    padding: 10px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation: none !important;
+    scroll-behavior: auto !important;
+    transition: none !important;
+  }
+}