update

backend/config.py

@@ -10,122 +10,123 @@ UNI_DIR = PROJECT_ROOT / "uni"
 
 MAX_CONCURRENT_GENERATIONS = 10
 
-# Lesbarkeits-Gate: deterministischer Prüfer (kleines deutsches Komplexitäts-Modell,
-# Skala 1–7). Zu schwere Sections gehen in die Lese-Prüfungs-Überarbeitung.
-# Fehlen transformers/torch oder das Modell → Gate stumm aus.
-LESBARKEIT_AKTIV = True
-LESBARKEIT_MODELL = "MiriUll/distilbert-german-text-complexity"
-# Anker auf der 1–7-Skala (TextComplexityDE): Leichte Sprache ~1,2; Wikipedia-Schnitt
-# ~3,22; ab MOS > 4 gilt ein Satz als „echt komplex" (Vereinfachungs-Grenze des Papers).
-LESBARKEIT_MAX = 3.5          # Section zu schwer, wenn der Satz-Schnitt darüber liegt
-LESBARKEIT_HART = 4.0         # Einzelsatz ab hier „hart"
-LESBARKEIT_HART_ANTEIL = 0.30  # … ODER wenn dieser Anteil der Sätze hart ist
+# Readability gate: deterministic checker (small German complexity model,
+# scale 1–7). Sections that are too hard go into the read-exam revision.
+# If transformers/torch or the model are missing → gate silently off.
+READABILITY_ACTIVE = True
+READABILITY_MODEL = "MiriUll/distilbert-german-text-complexity"
+# Anchors on the 1–7 scale (TextComplexityDE): plain language ~1.2; Wikipedia average
+# ~3.22; from MOS > 4 a sentence counts as "truly complex" (the paper's simplification cutoff).
+READABILITY_MAX = 3.5          # section too hard when the sentence average is above this
+READABILITY_HARD = 4.0         # an individual sentence is "hard" from here on
+READABILITY_HARD_SHARE = 0.30  # … OR when this share of sentences is hard
 
-# Bausteine-Konsolidierung: semantisches Embedding-Clustering statt LLM-Listen-Merge.
-# Ein kleines mehrsprachiges Satz-Embedding (mean-pool) bildet die Kandidaten-Cluster
-# GLOBAL (kein Chunk-Verlust) per Cosine + Union-Find. Titel-Varianten desselben Konzepts
-# ("Vertex Cover" / "Vertex Cover Definition") verschmelzen; der Konsens zählt danach die
-# echten Reader pro Cluster (≥2 = Konsens). Fehlen transformers/torch oder lädt das Modell
-# nicht → Embedding stumm aus, `_konsolidiere` fällt auf den alten Panel-Judge-Pfad zurück.
+# Block consolidation: semantic embedding clustering instead of an LLM list merge.
+# A small multilingual sentence embedding (mean-pool) builds the candidate clusters
+# GLOBALLY (no chunk loss) via cosine + union-find. Title variants of the same concept
+# ("Vertex Cover" / "Vertex Cover Definition") merge; the consensus then counts the
+# real readers per cluster (≥2 = consensus). If transformers/torch are missing or the model
+# won't load → embedding silently off, `_consolidate` falls back to the old panel-judge path.
 EMBEDDING_AKTIV = True
-EMBEDDING_MODELL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"  # CPU, mehrsprachig, ~470 MB
-# Stärkere (größere) CPU-Alternative bei Bedarf: "BAAI/bge-m3".
-# Konsolidierung = zweistufig: (1) Embedding bildet GROBE Ähnlichkeits-Blocks (High-Recall),
-# (2) ein LLM-Judge gruppiert JEDEN Block in die echten Bausteine (merge Paraphrasen, split
-# Über-Merges). Reines Threshold-Blocking erzeugt einen Giant-Component (alles verkettet) →
-# darum „Capped-Blocking": greedy nach Cosine mergen, aber Blockgröße deckeln. So bleiben die
-# LLM-Listen kurz und stabil (belegt: Embedding-Block + LLM-Judge ≈ 95 % Precision).
-EMBEDDING_BLOCK_FLOOR = 0.5   # Mindest-Cosine, damit zwei Kandidaten in EINEN Block dürfen
-EMBEDDING_BLOCK_CAP = 25      # max. Titel je Block (LLM-Liste kurz/stabil halten)
-# Subbaustein-Dedup: rein deterministisch (kein LLM). Subbausteine sind kurze Aussagen IM SELBEN
-# Baustein-Kontext — ab dieser Cosine sind zwei dieselbe Aussage (an aak geprüft: ≥0,88 ausnahmslos
-# echte Dubletten). Konservativ 0,90, damit verschiedene Aspekte (∈NP ≠ NP-schwer) getrennt bleiben.
+EMBEDDING_MODELL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"  # CPU, multilingual, ~470 MB
+# Stronger (larger) CPU alternative if needed: "BAAI/bge-m3".
+# Consolidation = two-stage: (1) the embedding builds COARSE similarity blocks (high recall),
+# (2) an LLM judge groups EACH block into the real blocks (merge paraphrases, split
+# over-merges). Pure threshold blocking creates a giant component (everything chained) →
+# hence "capped blocking": greedily merge by cosine, but cap the block size. This keeps the
+# LLM lists short and stable (evidenced: embedding block + LLM judge ≈ 95% precision).
+EMBEDDING_BLOCK_FLOOR = 0.5   # minimum cosine for two candidates to share ONE block
+EMBEDDING_BLOCK_CAP = 25      # max. titles per block (keep the LLM list short/stable)
+# Subblock dedup: purely deterministic (no LLM). Subblocks are short statements IN THE SAME
+# block context — from this cosine on two are the same statement (checked on aak: ≥0.88 are
+# without exception true duplicates). Conservative 0.90 so different aspects (∈NP ≠ NP-hard) stay separate.
 EMBEDDING_SUB_DUP = 0.90
 
-# Deckel für gleichzeitige CLI-Agenten-Prozesse (über alle Generierungen hinweg).
-# Eigene Spur für interaktive Aufrufe (Chat, Elemente), damit sie nicht hinter
-# laufenden Writern in der Warteschlange hängen.
+# Cap for concurrent CLI agent processes (across all generations).
+# Own lane for interactive calls (chat, elements) so they don't hang behind
+# running writers in the queue.
 MAX_CONCURRENT_AGENTS = 10
 MAX_CONCURRENT_INTERACTIVE = 8
 
-# Grace-Fenster der Konsens-Races (Bausteine, Guide, OnePager): Nach dem ersten
-# gültigen Ergebnis dürfen die übrigen Agenten noch so viele Sekunden fertig
-# werden (Kill nur, wenn das Minimum schon steht).
-KONSENS_GRACE = 300
+# Grace window of the consensus races (blocks, guide, OnePager): after the first
+# valid result the remaining agents may still become done for this many seconds
+# (kill only once the minimum is already in).
+CONSENSUS_GRACE = 300
 
-# Recherche-Race: längeres Grace-Fenster. Recherche treibt die ganze Bausteine-Anzahl;
-# bei langsamen Providern (z.B. MiniMax) sollen ALLE 5 Agenten fertig werden, nicht nur
-# das Quorum von 3. Pro-Agent-Timeout (TIMEOUTS["recherche"]=1800s) deckelt echte Hänger.
-RECHERCHE_GRACE = 900
+# Research race: longer grace window. Research drives the whole block count;
+# with slow providers (e.g. MiniMax) ALL 5 agents should become done, not just
+# the quorum of 3. The per-agent timeout (TIMEOUTS["research"]=1800s) caps real hangs.
+RESEARCH_GRACE = 900
 
-# Cap der Klärungs- und Prüf-Loops: maximale Runden, bis alles entschieden sein
-# muss. In der letzten Runde MUSS der Mapping-Agent jeden Eintrag entscheiden;
-# Prüf-Loops lassen Rest-Beanstandungen danach stehen.
-KONSENS_MAX_RUNDEN = 3
+# Cap of the clarification and check loops: maximum rounds until everything must be
+# decided. In the last round the mapping agent MUST decide every entry;
+# check loops leave any remaining objections standing after that.
+CONSENSUS_MAX_ROUNDS = 3
 
-# Crawler-Sichtung (Content/Noise) — deterministischer Regel-Filter statt LLM.
-# Match: Substring (klein) gegen URL UND Dateiname. Reihenfolge: keep > noise > min_chars > behalten.
-# Sonderregeln einfach hier ergänzen.
-CRAWL_KEEP_PATTERNS = ["learn-unit", "learn-course"]            # immer Content
-CRAWL_NOISE_PATTERNS = [                                         # eindeutig themenfremd → raus
+# Crawler triage (content/noise) — deterministic rule filter instead of an LLM.
+# Match: substring (lowercase) against URL AND file name. Order: keep > noise > min_chars > keep.
+# Just add special rules here.
+CRAWL_KEEP_PATTERNS = ["learn-unit", "learn-course"]            # always content
+CRAWL_NOISE_PATTERNS = [                                         # clearly off-topic → out
     "clubs", "events", "podcasts", "resources", "-u-",
     "academy", "pricing", "/plans", "career", "newsletter", "impressum", "login",
 ]
-CRAWL_MIN_CHARS = 400                                            # zu wenig Text → raus
+CRAWL_MIN_CHARS = 400                                            # too little text → out
 
-# LLM-Themen-Relevanz-Gate (nach dem Regel-Filter): je Content-Seite ja/nein gegen die Spec.
-# Trennt das Fachgebiet (z.B. Backend vs Frontend), was die globalen CRAWL_*-Regeln nicht können.
-QUELLE_RELEVANZ_CHUNK = 12       # Seiten je Rater-Paket (klein, da je Seite ein Snippet mitgeht)
-QUELLE_RELEVANZ_SNIPPET = 800    # Body-Zeichen je Seite im Prompt (URL ist Primärsignal)
+# LLM topic relevance gate (after the rule filter): per content page yes/no against the spec.
+# Separates the subject area (e.g. backend vs frontend), which the global CRAWL_* rules can't.
+QUELLE_RELEVANZ_CHUNK = 12       # pages per rater package (small, since a snippet ships per page)
+QUELLE_RELEVANZ_SNIPPET = 800    # body characters per page in the prompt (URL is the primary signal)
 
-# Timeouts pro Agenten-Schritt: (Basis-Sekunden, Sekunden pro Baustein/Section).
-# Gilt für alle Provider gleich — wer zu langsam ist, wird neu gestartet bzw. überholt.
+# Timeouts per agent step: (base seconds, seconds per block/section).
+# Applies equally to all providers — whoever is too slow gets restarted or overtaken.
 TIMEOUTS = {
-    "recherche":     (1800, 0),   # fix 30 min
-    "recherche_mapping": (600, 3),  # n = vorgemergte Einträge
-    "auswahl_mapping":   (600, 2),  # n = Rest-Einträge (Bausteine-Inventar)
-    "ergaenzung":    (900, 0),   # Themenfeld-Ergänzung bei Projekten (Web-Recherche)
+    "research":     (1800, 0),   # fixed 30 min
+    "research_mapping": (600, 3),  # n = pre-merged entries
+    "selection_mapping":   (600, 2),  # n = remaining entries (block inventory)
+    "ergaenzung":    (900, 0),   # subject-field extension for projects (web research)
     "plan":          (300, 5),
-    "plan_judge":    (600, 5),    # Judge liest bis zu 5 Gliederungen, n = Sections
-    "inhalt":        (600, 90),   # Inhalte je Baustein im Chunk identifizieren (Websuche)
-    "inhalt_check":  (300, 10),   # Inhalts-Prüfung je Baustein im Paket
-    "subbaustein":       (900, 45),  # Subbausteine je Baustein im Chunk finden (Websuche)
-    "subbaustein_check": (300, 15),  # Judge entscheidet strittige Subbausteine im Chunk
-    "stufe":             (300, 10),  # Subbausteine einstufen je Chunk
-    "stufe_check":       (300, 10),  # Judge entscheidet strittige Stufen im Chunk
-    "relevanz":          (300, 10),  # Subbausteine relevant/rand je Chunk
-    "relevanz_check":    (300, 10),  # Judge entscheidet strittige Relevanz im Chunk
-    "frage_muster":      (300, 15),  # Frage-Muster je Baustein (Subbausteine × Typen)
-    "frage_muster_check": (300, 10),  # Kritiker bereinigt die Muster-Tabelle je Baustein
-    "writer":        (600, 120),  # pro Section im Chunk
-    "lese_check":    (300, 10),   # pro Section im Paket
+    "plan_judge":    (600, 5),    # judge reads up to 5 outlines, n = sections
+    "content":        (600, 90),   # identify content per block in the chunk (web search)
+    "content_check":  (300, 10),   # content exam per block in the package
+    "subblock":       (900, 45),  # find subblocks per block in the chunk (web search)
+    "subblock_check": (300, 15),  # judge decides contested subblocks in the chunk
+    "level":             (300, 10),  # classify subblocks per chunk
+    "level_check":       (300, 10),  # judge decides contested levels in the chunk
+    "relevance":          (300, 10),  # subblocks relevant/peripheral per chunk
+    "relevance_check":    (300, 10),  # judge decides contested relevance in the chunk
+    "question_pattern":      (300, 15),  # question patterns per block (subblocks × types)
+    "question_pattern_check": (300, 10),  # critic cleans up the pattern table per block
+    "writer":        (600, 120),  # per section in the chunk
+    "lese_check":    (300, 10),   # per section in the package
 }
 
-# Zweck je Format — fließt in den Gliederungs-Judge (was der Guide leisten soll).
-FORMAT_ZWECK = {
+# Purpose per format — flows into the outline judge (what the guide should achieve).
+# German strings: these are inserted verbatim into the judge prompt → kept German on purpose.
+FORMAT_PURPOSE = {
     "Guide": "einen fokussierten Guide — alles Relevante ohne Randthemen",
     "FullGuide": "einen Komplett-Guide — das ganze Thema inkl. Randthemen",
     "Rest": "einen Ergänzungs-Guide — nur die Randthemen",
 }
 
-# Provider-Stacks: komplett unabhängig, einer kann jederzeit entfernt werden.
-# Rollen: "quick" = Massenarbeit (Recherche, Einordnung),
-#         "fast"  = Interaktion + Voten (Chat, Prüfung, Klärung, Elemente),
-#         "judge" = Mapping-/Judge-/Prüf-Agenten — kalt (niedrige Temperature,
-#                   ohne Thinking) für stabile Urteile; Claude/Lokal mappen auf "fast",
-#         "guide" = große Generierung (Vorschläge, Writer).
+# Provider stacks: completely independent, any one can be removed at any time.
+# Roles: "quick" = bulk work (research, classification),
+#        "fast"  = interaction + voting (chat, exam, clarification, elements),
+#        "judge" = mapping/judge/check agents — cold (low temperature,
+#                  no thinking) for stable verdicts; Claude/local map to "fast",
+#        "guide" = large generation (proposals, writer).
 DEFAULT_PROVIDER = "claude"
 PROVIDERS = {
     "claude": {
         "cli": "claude",
         "guide": "claude-opus-4-8[1m]",
         "fast": "claude-sonnet-4-6",
-        "judge": "claude-sonnet-4-6",  # CLI kennt keine Temperature
+        "judge": "claude-sonnet-4-6",  # the CLI has no temperature setting
         "quick": "claude-sonnet-4-6",
-        "env_key": None,  # Auth via CLAUDE_CODE_OAUTH_TOKEN oder ~/.claude
+        "env_key": None,  # auth via CLAUDE_CODE_OAUTH_TOKEN or ~/.claude
     },
-    # "minimax-kalt/…" ist KEIN eigener Stack, nur ein opencode-Provider-Eintrag
-    # (dev-ops/opencode.json) mit niedriger Temperature; M3 dort ohne Thinking.
+    # "minimax-kalt/…" is NOT its own stack, just an opencode provider entry
+    # (dev-ops/opencode.json) with low temperature; M3 there without thinking.
     "minimax": {
         "cli": "opencode",
         "guide": "minimax/MiniMax-M3",
@@ -141,6 +142,6 @@ PROVIDERS = {
         "judge": "ollama/qwen3.5:9b",
         "quick": "ollama/qwen3.5:9b",
         "env_key": None,
-        "check_url": "http://localhost:11434/api/tags",  # Ollama erreichbar?
+        "check_url": "http://localhost:11434/api/tags",  # Ollama reachable?
     },
 }