# Oggi – Ihr digitaler Programmassistent Assistent - Architektur, Betrieb und Sicherheitsgrenzen Stand: 13. Juli 2026 ## Ziel und Positionierung Oggi – Ihr digitaler Programmassistent unterstützt bei der Bedienung, nutzt freigegebene WEG-Daten und erklärt allgemeines WEG-Grundwissen. Der digitale Programmassistent Oggi ist kein autonomer Verwalter und ersetzt keine verbindliche Rechts-, Steuer- oder Fachberatung. ## Fuenf Ebenen 1. Deterministische Backend-Regeln fuer Authentifizierung, Rollen, Lizenz, Mandant und Aktionen. 2. Versionierte Orgatum-Wissensartikel mit Sprache, Rolle und Produktversion. 3. Explizit registrierte, mandantengebundene Backend-Werkzeuge. 4. Optionales externes Modell ueber die OpenAI Responses API fuer Sprache und Werkzeugplanung. 5. Regelbasierter Backend-Fallback und vollstaendig lokaler Desktop-Notfallmodus. Das Modell kann keine SQL-Abfragen erzeugen, keine Rolle vergeben, keine Mandantengrenze veraendern und keine Bestaetigung umgehen. ## Betriebsmodi - Online mit Modell: `OGGI_ENABLED=true`, `OGGI_AI_ENABLED=true` und `OPENAI_API_KEY` gesetzt. - Online ohne Modell: Backend-Werkzeuge, Retrieval und regelbasierte Antwort bleiben aktiv. - Backend-Ausfall: Desktop zeigt ausschliesslich lokale Bedienungshilfe und behauptet keine Live-Daten. - Mobile: Lesen, Fragen, Verlauf, Quellen und Schnellfragen; keine Hausgeld- oder sonstige Schreibaktion. Wenn der API-Schluessel fehlt, protokolliert der Server einmalig den technischen Fallbackstatus. Es entsteht keine API-Fehlerschleife. ## Intent-Taxonomie `src/assistant/taxonomy.js` enthaelt 15 Hauptbereiche mit stabilen Unter-Intent-IDs: - Bedienung, WEG/Objekt, Benutzer, Finanzen, Wirtschaftsplan, Jahresabrechnung - Versammlungen, Beschluesse, Dokumente, Instandhaltung - Oggi – Ihr digitaler Programmassistent, Lizenz, Datenschutz, Support und WEG-Grundwissen Die Taxonomie ist kein Katalog fest verdrahteter Antworten. Sie steuert Retrieval und sichere Vorauswahl von Werkzeugen. ## Wissensbasis und Retrieval Aktuelle JSON-Artikel liegen unter `weg-backend/src/assistant/knowledge-base/v1/`. Jeder Artikel fuehrt Artikel-ID, Titel, Kategorie, Sprache, Produktversion, Gueltigkeitsdatum, Pruefdatum, Status, Zielrollen, Text, Schritte, Verweise und Quellenbezeichnung. Die Retrieval-Schicht: - filtert `status=current`, Sprache und Rolle, - gewichtet die Produkt-Hauptversion, - behaelt Artikel- und Abschnittsreferenzen, - entfernt Duplikate, - begrenzt Treffer per `OGGI_RETRIEVAL_TOP_K`, - faellt bei deaktivierter/nebenlaeufig nicht ausreichender Suche auf die bestehende lokale Wissensbasis zurueck. Aktuell ist dies eine deterministische token- und synonymbasierte Relevanzsuche, keine Embedding-Datenbank. Eine echte Embedding-/Vektorsuche bleibt eine spaetere, separat zu evaluierende Ausbaustufe. ## Werkzeugkatalog Das Backend stellt derzeit strikte Definitionen fuer 25 Modellwerkzeuge bereit. Die zentrale Registry dokumentiert Modus, Rollen, Lizenzart, Mandantenbindung, Risiko, Bestaetigung, Audit, Ergebnislimit, Timeout und Fehlercodes. Implementierte Bereiche: - WEG-, Finanz-, Konten- und Ruecklagenzusammenfassung - offene Rechnungen und Rechnungsdetails - Budgetpositionen und Restbudget - Einheiten, privilegierte Eigentuemeransicht und Hausgeldstatus - Beschlusssuche und -details - Versammlungen, Agenda und Fristen - Dokumentmetadaten und optional indexierter Dokumentinhalt - Benutzerrolle, Lizenzstatus aus `weg_licenses`, Syncstatus und privilegierte Audit-Historie - Hausgeldvorschau mit separater Bestaetigung Noch nicht als produktive Werkzeuge vorhanden sind insbesondere Zahlungsstatus, Rueckstaende, Aufgaben und Instandhaltungsobjekte, weil das aktuelle Datenmodell dafuer keine ausreichend klare, vollstaendig getestete Quelle bereitstellt. ## Rollenmatrix | Funktion | Admin | Beirat | Eigentuemer | | --- | --- | --- | --- | | Allgemeine Zusammenfassungen | ja | ja | ja | | Einheiten ohne private Kontakte | ja | ja | ja | | Eigentuemer-/Rechnungsdetails | ja | ja | nein | | Freigegebene Dokumentmetadaten | ja | ja | eingeschraenkt | | Lizenz und Audit-Historie | ja | ja | nein | | Hausgeld vorschlagen/bestaetigen | ja | nein | nein | | Kritische Aktionen | nein | nein | nein | Die Datenbank-WEG stammt ausschliesslich aus dem authentifizierten Benutzer. Modellargumente fuer `community_id` oder `tenant_id` werden nicht akzeptiert. ## Dokumentanalyse Hinter den Flags `OGGI_DOCUMENT_INDEXING_ENABLED` und `OGGI_DOCUMENT_SEARCH_ENABLED` koennen PDF, DOCX, TXT und CSV serverseitig extrahiert, begrenzt, segmentiert und indexiert werden. Neue Uploads werden zunaechst als `admin`-sichtbar indexiert. Dokumenttext gilt immer als nicht vertrauenswuerdiger Dateninhalt. Verdacht auf Anweisungen wie "Ignoriere alle Systemregeln" wird markiert und in `assistant_document_security_events` ohne kompletten Dokumentinhalt protokolliert. Die aktuelle PDF-Referenz ist eine Zeichen-/Abschnittsreferenz; belastbare physische Seitenreferenzen sind noch nicht implementiert und werden daher nicht behauptet. ## Antwortformat Die API liefert kompatibel `answer`, `citations` und `proposedActions` sowie neu: - `summary`, `sources`, `suggested_actions` - `needs_clarification`, `clarification_question` - `needs_confirmation`, `confirmation_id` - `risk_notice`, `confidence` (`high`, `medium` oder `low`), `trace_id` Interne Gedankengaenge werden nicht ausgegeben. Desktop rendert Markdown-aehnliche Ueberschriften und trennt Benutzer/Oggi – Ihr digitaler Programmassistent optisch. Mobile rendert die Hauptantwort und Quellen; Datenkarten und sichere Mobile-Aktionsdialoge sind noch nicht vollstaendig umgesetzt. ## Schreibaktionen und Risiken LOW beantwortet Bedienungsfragen. MEDIUM liest WEG- oder Dokumentdaten nur mit Rolle und Quelle. HIGH braucht Vorschau und ausdrueckliche Bestaetigung. CRITICAL ist fuer Oggi – Ihr digitaler Programmassistent gesperrt. Die einzige produktiv implementierte Schreibaktion bleibt die monatliche Hausgeldanpassung. Sie verwendet aktuelle Daten, Vorschau, kurzlebigen JWT, erneute Rollen-/Lizenz-/Mandantenpruefung, Transaktion, Audit und Replay-Sperre. Aufgaben, Entwuerfe, Versand, Zahlung, Lastschrift, Loeschung und finale Abrechnung wurden nicht vorgetaeuscht oder voreilig freigeschaltet. ## OpenAI-Provider - zentrale Modellvariable `OPENAI_MODEL`, Standard `gpt-5.6` - Responses API und `store: false` - `AbortController`-Timeout - begrenzte Retries fuer 429, 5xx und Netzwerkfehler mit Backoff - Circuit Breaker nach konfigurierbarer Fehlerzahl - maximal begrenzte Werkzeugrunden und Ausgabetokens - kein Requestinhalt, API-Schluessel oder Responsebody in Fehlerlogs - automatischer Wissens-/Regel-Fallback ## Gespraechskontext Backend und Clients akzeptieren standardmaessig bis zu 20 aktuelle Nachrichten. Das Backend begrenzt zusaetzlich ueber ein approximiertes Tokenbudget und akzeptiert nur Rollen `user` und `assistant`. Der Backenddienst speichert keinen globalen Gespraechscache. Offene Hausgeldtoken sind an Benutzer und WEG gebunden und koennen in einer anderen WEG nicht bestaetigt werden. Eine persistente strukturierte Zusammenfassung und explizite UI-Ruecksetzung beim WEG-Wechsel sind noch nicht implementiert; die stateless Architektur verhindert jedoch einen serverseitigen Cross-Tenant-Verlaufscache. ## Beobachtbarkeit `ai_usage_log` enthaelt Modus, Modell, Token, Antwortdauer, Werkzeugzahl/-fehler, Retrievaltreffer, Fallbackgrund, Trace-ID und Fehlercode. `assistant_tool_access_log` erfasst datensparsam Werkzeug, Ergebnis, Dauer und Fehlercode. Fragen, Antworten, Dokumentinhalte, Passwoerter, Tokens und Geheimnisse werden dort nicht gespeichert. ## Evalkorpus `evals/oggi-evals.jsonl` enthaelt 10.000 eindeutige synthetische Szenarien, `evals/oggi-golden.jsonl` 500 deterministisch ausgewaehlte wichtige Faelle. Verteilung: | Gruppe | Anzahl | | --- | ---: | | Deutsch / Englisch | 8.500 / 1.500 | | Mehrfachdialog | 2.500 | | Tippfehler/Umgangssprache | 1.500 | | unvollstaendig / mehrdeutig | 1.000 / 1.000 | | Sicherheit | 1.000 | | Prompt Injection | 500 | | Offline | 500 | | widerspruechliche Daten | 500 | | Schreibaktionen / Ablehnungen | 1.250 / 1.000 | | davon erwartete Bestaetigungen | 1.062 | | Cross Tenant | 500 | Der Runner validiert Struktur, Taxonomiezuordnung, bekannte Rollen/Werkzeuge, Sicherheitsmarkierungen und Werkzeugregistry. Die aktuell ausgegebenen 100 Prozent sind deshalb kein Beleg fuer 100 Prozent reale Modellantwortqualitaet. Quellenqualitaet, Halluzinationen und Live-Modellverhalten muessen vor allgemeiner Freischaltung in Staging mit einem echten API-Schluessel separat gegradet werden. ## Reproduzierbare Befehle ```text npm run oggi:generate-evals npm run oggi:test npm run oggi:eval npm run oggi:eval:golden npm run oggi:eval:security npm run oggi:eval:offline npm run oggi:eval:tools npm run oggi:eval:tenants ``` ## Railway-Variablen Gesamt/Provider: `OGGI_ENABLED`, `OGGI_AI_ENABLED`, `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_REASONING_EFFORT`, `OPENAI_MAX_OUTPUT_TOKENS`, `OGGI_AI_TIMEOUT_MS`, `OGGI_AI_MAX_RETRIES`, `OGGI_AI_CIRCUIT_FAILURE_THRESHOLD`, `OGGI_AI_CIRCUIT_OPEN_MS`, `OGGI_MAX_TOOL_ROUNDS`. Responses werden unabhaengig von einer optional gesetzten Variable `OGGI_STORE_RESPONSES` immer mit `store: false` gesendet. Retrieval/Kontext: `OGGI_RETRIEVAL_ENABLED`, `OGGI_RETRIEVAL_TOP_K`, `OGGI_RETRIEVAL_MIN_SCORE`, `OGGI_KNOWLEDGE_VERSION`, `OGGI_MAX_RECENT_MESSAGES`, `OGGI_MAX_CONTEXT_TOKENS`. Rollout: `OGGI_DOCUMENT_INDEXING_ENABLED`, `OGGI_DOCUMENT_SEARCH_ENABLED`, `OGGI_WRITE_ACTIONS_ENABLED`, `OGGI_MOBILE_ACTIONS_ENABLED`, `OGGI_EVAL_LOGGING_ENABLED`, `OGGI_TOOL_AUDIT_ENABLED`. `OPENAI_API_KEY` ist ausschliesslich ein Railway-Secret. Kein echter Wert gehoert in Repository, Client, Browser, Logs oder Fehlermeldungen. ## Empfohlener Rollout 1. lokale Tests und Schema-Check 2. Railway-Staging mit Testdaten 3. Shadow Mode ohne sichtbare Schreibaktionen 4. interne Pilotnutzer 5. kleine Kundengruppe 6. allgemeine Freischaltung erst nach Live-Evals Bei Problemen: `OGGI_AI_ENABLED=false`, danach bei Bedarf Retrieval/Dokumente/Schreibaktionen einzeln deaktivieren. Der regel- und wissensbasierte Modus bleibt erreichbar. ## Troubleshooting - Kein API-Key: erwarteter Fallback, kein Ausfall. - KI-Timeout/429/5xx: Retry, danach Circuit Breaker und Fallback. - Keine Dokumenttreffer: Flags, Uploadzeitpunkt, Rolle und Sichtbarkeit pruefen. - Werkzeug verweigert: Rolle, aktuelle Lizenz und serverseitige Registry pruefen. - Schreibaktion fehlt: Desktop-Capability und `OGGI_WRITE_ACTIONS_ENABLED` pruefen. - Mobile zeigt keinen Aktionsbutton: beabsichtigt, Mobile-Aktionen sind nicht freigegeben. ## Bekannte technische Schulden Der Backend-Produktionsdependency-Audit ist ohne Befund. Der getrennte Mobile-Stack basiert noch auf Expo 51/React Native 0.74; `npm audit` meldet dort transitive Schwachstellen, deren automatischer Fix einen breaking Upgrade auf eine neue Expo-/React-Native-Hauptversion erzwingen wuerde. Dieser Plattform-Upgrade muss separat geplant, migriert und auf echten Geraeten getestet werden. Er wurde nicht ungeprueft per `--force` ausgefuehrt.