Initial commit

This commit is contained in:
2026-11-16 16:29:32 +01:00
commit 97e5c9ef4d
37 changed files with 5932 additions and 0 deletions
+178
View File
@@ -0,0 +1,178 @@
"""Textnormalisierung und Fuzzy-Vergleich (RapidFuzz).
Wichtig: Die Normalisierung wird ausschliesslich fuer Vergleiche und fuer den
Suchindex verwendet. Der gespeicherte Originaltext bleibt unveraendert.
"""
from __future__ import annotations
import re
import unicodedata
from dataclasses import dataclass
from rapidfuzz import fuzz
# Satzzeichen und Symbole, die beim Vergleich stoeren. Wortzeichen (Buchstaben,
# Ziffern, Unterstrich) bleiben erhalten.
_PUNCT_RE = re.compile(r"[^\w\s]", re.UNICODE)
_WHITESPACE_RE = re.compile(r"\s+", re.UNICODE)
# Sehr haeufige deutsche Fuellwoerter. Sie werden beim Vorfilter nicht als
# belastbare Uebereinstimmung gewertet, damit "der/die/das" allein keine
# Kandidaten erzeugt.
STOPWORDS = frozenset(
{
"der", "die", "das", "den", "dem", "des", "ein", "eine", "einer", "eines",
"einem", "einen", "und", "oder", "aber", "als", "auch", "auf", "aus", "bei",
"bin", "bis", "da", "dann", "dass", "doch", "dort", "du", "durch", "er",
"es", "hat", "ich", "ihm", "ihn", "ihr", "im", "in", "ist", "mit", "nach",
"nicht", "noch", "nun", "nur", "ob", "so", "sich", "sie", "sind", "um",
"und", "vom", "von", "vor", "war", "was", "wenn", "wie", "wir", "wo", "zu",
"zum", "zur", "the", "and", "of", "to", "in", "a", "is",
}
)
def normalize_text(text: str) -> str:
"""Normalisiert Text fuer Vergleiche: NFKC, Kleinschreibung, ohne Satzzeichen."""
if not text:
return ""
normalized = unicodedata.normalize("NFKC", text).casefold()
normalized = _PUNCT_RE.sub(" ", normalized)
return _WHITESPACE_RE.sub(" ", normalized).strip()
def tokenize(text: str) -> list[str]:
"""Normalisierte Wortliste eines Textes."""
normalized = normalize_text(text)
return normalized.split() if normalized else []
def tokenize_original(text: str) -> list[str]:
"""Wortliste mit Originaltext inklusive anhängender Satzzeichen (fuer die Ausgabe)."""
if not text:
return []
return [token for token in _WHITESPACE_RE.split(text.strip()) if token]
def token_norm(token: str) -> str:
"""Normalisiert ein einzelnes Originalwort."""
return normalize_text(token)
def is_stopword(token: str) -> bool:
return token in STOPWORDS
@dataclass(frozen=True)
class WindowScore:
"""Ergebnis eines Fenstervergleichs."""
score: float
exact: bool
def score_window(query_normalized: str, window_normalized: str) -> WindowScore:
"""Vergleicht Suchanfrage und Textfenster und liefert einen Wert 0-100.
Es werden mehrere RapidFuzz-Kennzahlen kombiniert, damit fehlende,
zusaetzliche, vertauschte oder falsch erkannte Woerter nicht sofort zum
Verlust des Treffers fuehren.
"""
if not query_normalized or not window_normalized:
return WindowScore(0.0, False)
if query_normalized == window_normalized:
return WindowScore(100.0, True)
# Hinweis: Eine reine Teilzeichenketten-Pruefung ist hier absichtlich NICHT
# enthalten. Sie wuerde z. B. das Fenster "Leider" fuer die Anfrage
# "Leider zu spaet" mit 100 bewerten und den Treffer auf ein Wort
# zusammenfallen lassen. Teiluebereinstimmungen werden stattdessen ueber
# die gewichteten RapidFuzz-Kennzahlen unten bewertet.
ratio = fuzz.ratio(query_normalized, window_normalized)
token_set = fuzz.token_set_ratio(query_normalized, window_normalized)
weighted = fuzz.WRatio(query_normalized, window_normalized)
partial = fuzz.partial_ratio(query_normalized, window_normalized)
# partial_ratio neigt bei kurzen Fenstern zu hohen Werten, daher nur
# gedämpft einbeziehen.
# token_set_ratio/WRatio/partial_ratio bewerten eine Teilmenge der Anfrage
# mit 100. Ohne Daempfung wuerde ein einzelnes Wort einer mehrwoertrigen
# Anfrage als perfekter Treffer gelten. Daher werden diese Kennzahlen mit
# dem Laengenverhaeltnis gewichtet, wenn das Fenster kuerzer ist.
length_factor = min(1.0, len(window_normalized) / max(1, len(query_normalized)))
score = max(
ratio,
token_set * length_factor,
weighted * length_factor,
partial * 0.92 * length_factor,
)
return WindowScore(min(100.0, round(score, 2)), False)
def token_overlap(query_tokens: list[str], window_tokens: list[str]) -> float:
"""Anteil der Anfragewoerter, die im Fenster vorkommen (0..1)."""
if not query_tokens:
return 0.0
window_set = set(window_tokens)
hits = sum(1 for token in query_tokens if token in window_set)
return hits / len(query_tokens)
def significant_overlap(query_tokens: list[str], window_tokens: list[str]) -> float:
"""Wie :func:`token_overlap`, aber Fuellwoerter zaehlen nur halb."""
if not query_tokens:
return 0.0
window_set = set(window_tokens)
total = 0.0
hits = 0.0
for token in query_tokens:
weight = 0.5 if is_stopword(token) else 1.0
total += weight
if token in window_set:
hits += weight
if total == 0:
return 0.0
return hits / total
def _escape_fts_token(token: str) -> str:
return '"' + token.replace('"', '""') + '"'
def build_fts_query(tokens: list[str], prefix_min_length: int = 4) -> str:
"""Baut eine FTS5-Anfrage aus ODER-verknuepften Woertern.
Praefixsuche fuer laengere Woerter faengt deutsche Flexionsformen und
Zusammensetzungen ab. Die Anfrage ist bewusst weit gefasst: sie dient nur
der Kandidatensuche, die Bewertung erfolgt spaeter per Fuzzy-Vergleich.
"""
parts: list[str] = []
seen: set[str] = set()
for token in tokens:
if len(token) < 2 or token in seen:
continue
seen.add(token)
escaped = _escape_fts_token(token)
if len(token) >= prefix_min_length:
parts.append(f"{escaped}*")
else:
parts.append(escaped)
return " OR ".join(parts)
def trigram_terms(tokens: list[str], max_terms: int = 32) -> list[str]:
"""Sinnvolle Trigramm-Anfragen aus laengeren Anfragewoertern."""
terms: list[str] = []
seen: set[str] = set()
for token in tokens:
if len(token) < 4 or token in seen:
continue
seen.add(token)
terms.append(token)
if len(terms) >= max_terms:
break
return terms