Was wir beim Bau unseres eigenen Support-Bot-Widgets gelernt haben (Chat mit deinem Content)

• Retrieval bricht vorhersehbar
• Latenz zerstoert Vertrauen, bevor die erste Antwort landet
• Access Control ist leicht falsch zu machen
• Prompt Injection wird zu "Content Poisoning"
• Antworten muessen auditierbar sein, sonst wird der Bot zum Support-Risiko

Was wir gebaut haben (Requirements und Constraints)

• Schnelles First Token: Nutzer sollen schnell eine Reaktion sehen, auch wenn der Assistant im Hintergrund erst "suchen" muss.
• Grounded Answers: Antworten muessen durch Content gestuetzt sein, den wir wirklich ausliefern.
• Read-only by default: der Assistant darf Content nicht mutieren.
• Multi-Locale ready: unsere Site ist lokalisiert; der Assistant soll Locales nicht beliebig mischen.
• Safe Escalation: wenn er nicht sicher antworten kann, soll er sauber eskalieren (Contact/Support), ohne zu halluzinieren.

Der Assistant soll sich wie ein vorsichtiger Engineer verhalten, der unsere Website liest, nicht wie ein kreativer Writer, der improvisiert.

Ein funktionierendes Modell: "Support Bot = Search + Navigation + Synthesis"

1. Search: Kandidaten-Seiten/Sections identifizieren.
2. Navigate: Seiten oeffnen, Headings scannen, Links folgen, Query verfeinern.
3. Synthesize: eine kurze, korrekte Antwort liefern, mit Pointern, woher sie kommt.

Lesson 1: Chunk-only RAG faellt auseinander, wenn die Antwort ueber mehrere Seiten geht

• die Antwort ist auf zwei Seiten verteilt
• die "exakte Syntax" steckt in einem Codeblock, der nicht gerankt wurde
• die Frage ist underspecified, Embedding Match ist "close enough"
• die richtige Seite hat wenig lexikalische Ueberschneidung

Lesson 2: Gib dem Assistant deterministische Primitives (Docs-as-Files)

• find die Seite
• open sie
• scannen Headings
• suchen nach exakten Tokens
• folgen internen Links
• wiederholen, bis wir die Antwort beweisen koennen

• jede Seite ist ein "File"
• Directories repraesentieren Sections (oder URL-Pfadsegmente)
• der Assistant kann ls, find, cat und grep

• auditierbar sind (Tool Calls lassen sich loggen)
• deterministisch sind
• skalierbar sind (Exploration ohne Hardcoding)

Architektur (die einfachste Version, die funktioniert)

Browser widget
  -> /api/support-chat (stream)
      -> Retrieval layer (lexical + vector)
      -> Tool layer ("filesystem" over content)
      -> Answer synthesis (grounded prompt + citations)
      -> Observability (logs + traces + eval hooks)

Datenmodell: pages, chunks und ein path tree

• page: canonical URL/slug + title + locale + visibility + lastmod + headings
• chunk: { page, chunk_index, text, embedding, tokens, hash }
• path_tree: { "services/seo": { isPublic: true, groups: [] }, ... }

• der Assistant braucht eine Map: "was existiert"
• Access Control wird strukturell (Paths vor Sessionstart prunen)
• ls/find wird schnell und gut cachebar

Ingestion-Pipeline: eine Website zu einer verlaesslichen Knowledge-Surface machen

• Marketing Copy + Components
• MDX und Headings, die nicht sauber auf HTML mappen
• Listing-Seiten, die Content-Bloecke wiederholen
• Locale-Varianten, die teilweise divergieren

1. Pages discovern: Sitemap + bekannte Route-Liste.
2. Rendered HTML fetchen: was Nutzer (und Crawler) wirklich sehen.
3. Main Content extrahieren: Nav, Footer, Cookie Banner, wiederholte UI entfernen.
4. Normalisieren: Whitespace, Tracking-Query-Strings aus Links entfernen.
5. Segmentieren:
   • page-level Record fuer Navigation und Zitate
   • chunk-level Records fuer Retrieval
6. Annotieren:
   • locale
   • visibility (public, client-only, internal)
   • headings outline
   • outbound internal links

Retrieval: lexical und vector kombinieren, bevor du "das Model fragst"

• lexical search fuer exakte Tokens (Identifier, Akronyme, Error Codes)
• vector search fuer semantische Naehe (vage Fragen)

• Pages mit falscher Locale ablehnen (ausser explizit angefragt)
• canonical Pages gegenueber Tag-/Listing-Duplikaten bevorzugen
• Pages bevorzugen, deren Headings gut zur Query passen

Tool-Design: was der Assistant darf (und was nicht)

• Directories listen: ls /services
• Pfade suchen: find -name "billing"
• eine ganze Seite lesen: cat /services/seo
• innerhalb von Content suchen: grep -ri "canonical" /

• Content schreiben oder editieren
• beliebige URLs fetchen
• beliebige Network Calls

Latenz: echte Filesystems sind zu langsam fuer interaktiven Chat

• Cold Start wird sichtbar
• Chat fuehlt sich kaputt an
• du wirst zu Komplexitaet wie Warm Pools verleitet

• ls und find laufen ueber den gecachten Path Tree
• cat setzt eine Page aus gespeicherten Chunks zusammen (sortiert nach chunk_index)
• Ergebnisse werden per Session gecacht (und teilweise global, wenn safe)

Cache, was sich wiederholt: path tree, pages und "grep targets"

• dieselben Sections listen
• dieselben 5-10 Kernseiten oeffnen
• dieselben Tokens greppen

• den Path Tree
• rekonstruierte Full Pages
• recente Grep-Kandidaten

RBAC: Access Control muss strukturell sein, nicht prompt-basiert

• user-scoped Path Tree bauen
• alles prunen, was der User nicht sehen darf
• denselben Filter auf jede Query und jeden Page Read anwenden

Guardrails: wie wir "confident wrong" Antworten reduziert haben

Regel 1: Kein Evidence, keine Antwort

• sagen, dass er es nicht verifizieren konnte
• zeigen, was er geprueft hat (Pages/Sections)
• einen naechsten Schritt anbieten (Contact/Support)

Regel 2: Bei kritischen Details lieber zitieren als paraphrasieren

• relevante Saetze aus der gelesenen Page zitieren
• Synthesis minimal halten

Regel 3: Strikt bei Locale und canonical Pages bleiben

• die Locale bevorzugen
• Sprachen nicht mischen
• nur auf Default-Locale fallbacken, wenn die Locale-Page nicht existiert

Das "grep problem": Killer-Feature, aber nur mit Plan

1. coarse filter ueber den Index (welche Pages koennten das Token enthalten)
2. fine filter in memory ueber gecachten Page Text, um exakte Treffer + Kontext zu extrahieren

Widget-UX: die UI entscheidet ueber Vertrauen

• Streaming Tokens mit stabilem Layout (keine jumpy Reflows)
• klare States:
  • "Searching..."
  • "Reading page..."
  • "Answering..."
• kurze, inline Zitate:
  • "From: /services/seo"
  • "From: /legal/privacy"
• Fallbacks, die nicht wie ein Fail wirken:
  • "Ich habe X und Y geprueft, konnte es aber nicht bestaetigen; hier ist, wie du uns erreichst."

Observability: logge Reads, nicht nur Tokens

• Tool Calls (welche Pfade gelistet/gelesen/gesucht wurden)
• welche Pages als Evidence genutzt wurden
• Answer length und Latenz-Buckets
• "could not verify" Raten
• Escalation-Raten (Contact Clicks)

• welche Pages fehlen wichtige Informationen?
• welche Fragen finden nie Evidence?
• welche Pages verwirren Nutzer und muessen umstrukturiert werden?

Ein praktischer Build-Checklist (was wir wieder so machen wuerden)

• indexiere die gerenderte Site und speichere page-level Records
• kombiniere lexical + vector Retrieval
• addiere eine Exploration-Tool-Layer (files + grep)
• prune Content fuer RBAC vor Sessionstart
• halte Tools read-only by default
• setze die Regel "no evidence, no answer"
• mache "searching/reading/answering" in der UI sichtbar
• logge Tool Calls, damit du Failures debuggen kannst

• Web Development
• Web Apps
• AI
• Contact