.env.example hinzugefügt

.env.example

@@ -0,0 +1,620 @@
+###############################################################################
+# GLPI AI AGENT
+#
+# Hinweise:
+# - Boolesche Werte: true | false
+# - Zeitangaben: z. B. 30s, 5m, 2h, 72h
+# - Prozent-/Scorewerte werden als 0.0 bis 1.0 angegeben:
+#     0.70 = 70 %
+# - Komma-separierte Listen ohne Leerzeichen schreiben.
+#
+# WICHTIG:
+# DRY_RUN=true verhindert Änderungen an GLPI.
+# Für die Einführungs-/Testphase unbedingt aktiviert lassen.
+###############################################################################
+
+
+###############################################################################
+# 01. ALLGEMEINER BETRIEB
+###############################################################################
+
+# true:
+#   Agent analysiert Tickets, schreibt aber keine Änderungen nach GLPI.
+# false:
+#   freigegebene Kategorieänderungen und Antworten werden tatsächlich geschrieben.
+DRY_RUN=true
+
+# Logging-Level.
+# Mögliche Werte:
+#   debug | info | warn | error
+LOG_LEVEL=info
+
+# HTTP-Listener für WebUI, API, /healthz und /readyz.
+HTTP_ADDR=:7080
+
+# Persistente Laufzeitdaten:
+# - Audit-Logs
+# - Knowledge-Index
+# - Web-KB
+# - Lernbeispiele
+# - GLPI-KB-Cache
+DATA_DIR=./data
+
+
+###############################################################################
+# 02. WEBINTERFACE / AUTHENTIFIZIERUNG
+###############################################################################
+
+# Dashboard/API-Benutzer.
+WEB_USERNAME=admin
+
+# Unbedingt ein langes zufälliges Passwort verwenden.
+WEB_PASSWORD=<SECRET>
+
+# false = Authentifizierung erforderlich.
+# true  = WebUI ohne Login erreichbar.
+#
+# In Produktion dringend false lassen.
+# KNOWLEDGE_WEB_EDIT_ENABLED=true ist zusammen mit anonymem Zugriff nicht
+# empfehlenswert bzw. wird je nach Agent-Version abgelehnt.
+WEB_ALLOW_ANONYMOUS=false
+
+# Kennzeichnung automatisch ausgewählter KI-Inhalte.
+# true = TrustedNet-KI-Badge wird jeder automatischen Antwort vorangestellt.
+AI_CONTENT_LABEL_ENABLED=true
+
+
+###############################################################################
+# 03. OPTIONALER GLPI-WEBHOOK
+###############################################################################
+
+# Optionales Shared Secret für eingehende GLPI-Webhooks.
+#
+# Der Absender muss denselben Wert z. B. als:
+#   X-Webhook-Secret
+# übertragen.
+#
+# Leer lassen, wenn kein Webhook verwendet wird.
+WEBHOOK_SECRET=<SECRET>
+
+
+###############################################################################
+# 04. GLPI 11 / HIGH-LEVEL API / OAUTH2
+###############################################################################
+
+GLPI_URL=https://glpi.example.com
+
+# Aktuell verwendete High-Level-API-Version.
+GLPI_API_VERSION=v2.3
+
+# OAuth2-Zugangsdaten des Service Accounts.
+GLPI_CLIENT_ID=<SECRET>
+GLPI_CLIENT_SECRET=<SECRET>
+GLPI_USERNAME=ai
+GLPI_PASSWORD=<SECRET>
+
+# Numerische GLPI-Benutzer-ID des Agent-Service-Accounts.
+#
+# Wichtig für die Erkennung:
+# "Ist dieses Followup vom Agenten selbst oder von einem Menschen?"
+GLPI_AGENT_USER_ID=999
+
+# true erlaubt unverschlüsseltes HTTP.
+# Nur für lokale Entwicklungs-/Testsysteme verwenden.
+GLPI_ALLOW_INSECURE_HTTP=false
+
+# Nur Tickets mit diesen GLPI-Status-IDs werden verarbeitet.
+#
+# Beispiel:
+#   1       = nur "Neu"
+#   1,2     = mehrere erlaubte Status
+#
+# Fail-closed: lieber zunächst nur Status 1 erlauben.
+GLPI_ALLOWED_STATUS_IDS=1
+
+# Wie oft GLPI auf neue/geänderte Tickets geprüft wird.
+GLPI_POLL_INTERVAL=30s
+
+# Maximal geladene Tickets pro Poll.
+GLPI_POLL_LIMIT=50
+
+# Optionaler serverseitiger GLPI-Filter.
+# Die Agent-Policy prüft GLPI_ALLOWED_STATUS_IDS trotzdem nochmals selbst.
+#
+# Filter-Syntax gegen /api.php/doc der eigenen GLPI-Instanz prüfen.
+GLPI_TICKET_FILTER=status.id==1
+
+# HTTP-Timeout für GLPI-API-Aufrufe.
+GLPI_TIMEOUT=20s
+
+
+###############################################################################
+# 05. OLLAMA / LLM
+###############################################################################
+
+# Innerhalb Docker Compose typischerweise:
+#   http://ollama:11434
+#
+# Bei nativem Betrieb:
+#   http://localhost:11434
+OLLAMA_URL=http://ollama:11434
+
+# Chat-/Entscheidungsmodell.
+OLLAMA_MODEL=qwen3:8b
+
+# Embedding-Modell für Knowledge-Retrieval.
+OLLAMA_EMBEDDING_MODEL=embeddinggemma
+
+# Retrieval-Profil:
+#   auto  = erkennt z. B. embeddinggemma und verwendet passende Query-/Doc-Prompts
+#   plain = keine modellspezifischen Retrieval-Prompts
+#
+# Empfohlen:
+KNOWLEDGE_EMBEDDING_PROFILE=auto
+
+# Maximale Dauer eines einzelnen Ollama-Requests.
+OLLAMA_TIMEOUT=10m
+
+# Maximale Anzahl generierter Tokens für strukturierte Entscheidungen.
+OLLAMA_NUM_PREDICT=768
+
+# Anzahl Wiederholungen bei ungültigem/unvollständigem JSON.
+OLLAMA_JSON_RETRIES=1
+
+# Modell nach Nutzung im Speicher halten.
+OLLAMA_KEEP_ALIVE=10m
+
+# Thinking bei unterstützten Modellen deaktivieren.
+# Für die strukturierte Ticketklassifikation normalerweise sinnvoll.
+OLLAMA_THINK=false
+
+# Maximale parallele Requests an Ollama.
+#
+# Bei einer GPU/einem Ollama-Slot zunächst 1 verwenden.
+OLLAMA_MAX_CONCURRENT=1
+
+
+###############################################################################
+# 06. KNOWLEDGE BASE / RAG - GRUNDKONFIGURATION
+###############################################################################
+
+# Verzeichnis für statische / Git-verwaltete Knowledge-JSONs.
+KNOWLEDGE_DIR=./knowledge
+
+# false deaktiviert das komplette RAG/Embedding-System.
+RAG_ENABLED=true
+
+# Verhalten bei externen/String-Kategorien aus gemeinsam genutzten KB-Dateien.
+#
+# Mögliche Werte:
+#
+#   unscoped
+#     KB wird trotzdem geladen.
+#     Fremdkategorien dienen weiterhin als Retrieval-Tags.
+#     Nicht zuordenbare GLPI-Kategorien werden nicht erzwungen.
+#
+#   skip
+#     KB mit nicht zuordenbaren Kategorien komplett überspringen.
+#
+#   strict
+#     unbekannte Kategorie erzeugt einen Start-/Scanfehler.
+#
+# Für gemeinsam genutzte Datenbestände empfohlen:
+KNOWLEDGE_CATEGORY_MODE=unscoped
+
+# Optionales Mapping externer Kategorien auf GLPI-ITIL-Kategorie-IDs.
+#
+# Beispiel:
+# {
+#   "Active Directory": 2,
+#   "Outlook": 12,
+#   "E-Mail": 12,
+#   "Security": [20,21]
+# }
+KNOWLEDGE_CATEGORY_MAP_FILE=/app/data/knowledge-category-map.json
+
+# Dateien anhand von Glob-Mustern ignorieren.
+#
+# Beispiele:
+# KNOWLEDGE_IGNORE_GLOBS=KB-SEC-ATTCK-*.json
+# KNOWLEDGE_IGNORE_GLOBS=legacy-*.json,external-only-*.json
+#
+# Leer = nichts explizit ignorieren.
+KNOWLEDGE_IGNORE_GLOBS=
+
+
+###############################################################################
+# 07. PERSISTENTER / INKREMENTELLER KNOWLEDGE-INDEX
+###############################################################################
+
+# Mögliche Werte:
+#
+#   incremental
+#     vorhandenen persistenten Index sofort laden und Änderungen im Hintergrund
+#     nachziehen. Für Produktion empfohlen.
+#
+#   rebuild
+#     Index vollständig neu aufbauen.
+#
+#   readonly
+#     nur vorhandenen Snapshot benutzen, keine Quelldateien aktualisieren.
+#
+KNOWLEDGE_INDEX_MODE=incremental
+
+# Anzahl Embedding-Inputs pro Batch.
+KNOWLEDGE_EMBED_BATCH_SIZE=64
+
+# Intervall für Hintergrundprüfung auf neue/geänderte/gelöschte Knowledge-Dateien.
+#
+# 0 = kein automatischer Rescan.
+KNOWLEDGE_INDEX_SCAN_INTERVAL=5m
+
+
+###############################################################################
+# 08. KNOWLEDGE-RETRIEVAL / KANDIDATENAUSWAHL
+###############################################################################
+
+# Minimale Retrieval-Relevanz, damit eine KB überhaupt als plausibler Kandidat
+# betrachtet werden kann.
+#
+# KEINE Wahrscheinlichkeit.
+KNOWLEDGE_RETRIEVAL_FLOOR=0.30
+
+# Maximaler Abstand zum besten Treffer.
+#
+# Beispiel:
+# bester Treffer       = 0.82
+# MAX_GAP              = 0.20
+# dynamischer Cutoff   = 0.62
+#
+# Nur KBs >= 0.62 werden in diesem Beispiel an die KI weitergegeben.
+KNOWLEDGE_CANDIDATE_MAX_GAP=0.20
+
+# Maximale Anzahl KB-Kandidaten, die Ollama erhält.
+#
+# Das ist nur die Obergrenze.
+# Durch Floor und Max-Gap können es deutlich weniger sein.
+KNOWLEDGE_TOP_K=6
+
+# Anzahl Kandidaten, die für Dashboard/Audit gespeichert werden.
+# Kann größer als KNOWLEDGE_TOP_K sein.
+KNOWLEDGE_AUDIT_TOP_K=10
+
+
+###############################################################################
+# 09. HYBRID-RETRIEVAL / RANKING
+###############################################################################
+
+# Gewichtung des Kandidaten-Rankings.
+#
+# Summe sollte sinnvollerweise 1.0 ergeben.
+# Fehlende Metadaten werden nicht negativ gewertet; vorhandene Komponenten
+# werden intern entsprechend berücksichtigt.
+
+# Embedding-/Chunk-Semantik
+KNOWLEDGE_WEIGHT_SEMANTIC=0.45
+
+# Ähnlichkeit Ticket-Betreff <-> KB-Titel
+KNOWLEDGE_WEIGHT_TITLE=0.20
+
+# Lexikalische Übereinstimmungen / typische Helpdesk-Begriffe
+KNOWLEDGE_WEIGHT_LEXICAL=0.20
+
+# Explizite KB-Keywords
+KNOWLEDGE_WEIGHT_KEYWORDS=0.075
+
+# GLPI-Kategorie / bestätigte Lernsignale
+KNOWLEDGE_WEIGHT_CATEGORY=0.075
+
+
+###############################################################################
+# 10. FINALE KNOWLEDGE-EVIDENZ FÜR AUTO-REPLY
+###############################################################################
+
+# Mindestwert der finalen Evidenz für eine automatische Antwort.
+#
+# WICHTIG:
+# Das ist NICHT mehr nur der rohe Retrieval-Score.
+#
+# Finale Evidenz berücksichtigt:
+# - Retrieval
+# - KI-Auswahl / KI-Confidence
+# - Kategorieübereinstimmung
+#
+KNOWLEDGE_MIN_SCORE=0.70
+
+# Gewicht des Retrieval-Scores in der finalen Evidenz.
+KNOWLEDGE_EVIDENCE_WEIGHT_RETRIEVAL=0.45
+
+# Gewicht der KI-Auswahl / Reply-Confidence.
+KNOWLEDGE_EVIDENCE_WEIGHT_AI=0.35
+
+# Gewicht der Kategorieübereinstimmung.
+KNOWLEDGE_EVIDENCE_WEIGHT_CATEGORY=0.20
+
+
+###############################################################################
+# 11. KNOWLEDGE-CHUNKING
+###############################################################################
+
+# Anzahl Wörter pro KB-Chunk.
+KNOWLEDGE_CHUNK_WORDS=160
+
+# Überlappung zwischen benachbarten Chunks.
+KNOWLEDGE_CHUNK_OVERLAP_WORDS=30
+
+# Maximale Anzahl Chunks pro Knowledge-Dokument.
+KNOWLEDGE_MAX_CHUNKS_PER_DOC=24
+
+# Maximale Anzahl Chunks eines langen Tickets.
+KNOWLEDGE_MAX_QUERY_CHUNKS=64
+
+# Begrenzung der Kategorien im Ollama-Prompt.
+# Verhindert übergroße Prompts bei sehr großen GLPI-Kategorieäumen.
+CATEGORY_PROMPT_LIMIT=80
+
+
+###############################################################################
+# 12. KNOWLEDGE-QUELLEN / TRUST POLICY
+###############################################################################
+
+# Nur diese Source-Labels dürfen überhaupt durchsucht werden.
+#
+# Beispiel:
+#   internal-kb,glpi-kb,vendor-docs
+KNOWLEDGE_ALLOWED_SOURCES=internal-kb,glpi-kb
+
+# Nur diese Quellen dürfen automatische Antworten auslösen.
+#
+# Muss Teilmenge von KNOWLEDGE_ALLOWED_SOURCES sein.
+#
+# "none" = Auto-Reply aus Knowledge-Quellen komplett deaktivieren.
+KNOWLEDGE_AUTO_REPLY_SOURCES=internal-kb,glpi-kb
+
+# Webbasierte CRUD-Verwaltung eigener Knowledge-Artikel.
+#
+# Web-Artikel liegen unter:
+#   DATA_DIR/knowledge-managed/
+#
+# KNOWLEDGE_DIR bleibt read-only / Git-verwaltet.
+KNOWLEDGE_WEB_EDIT_ENABLED=true
+
+
+###############################################################################
+# 13. GLPI KNOWLEDGE BASE - READ-ONLY CONNECTOR
+###############################################################################
+
+# GLPI Knowledge Base synchronisieren.
+GLPI_KB_ENABLED=true
+
+# auto:
+#   KnowbaseItem-Route wird aus /api.php/doc.json ermittelt.
+#
+# Alternativ kann ein expliziter API-Pfad angegeben werden.
+GLPI_KB_PATH=auto
+
+# Optionaler serverseitiger Filter.
+# Leer = alle für den Service-Account sichtbaren KB-Artikel.
+GLPI_KB_FILTER=
+
+# Maximale Anzahl synchronisierter GLPI-KB-Artikel.
+GLPI_KB_LIMIT=500
+
+# Synchronisationsintervall.
+GLPI_KB_SYNC_INTERVAL=10m
+
+# Source-Label synchronisierter GLPI-KBs.
+# Muss in KNOWLEDGE_ALLOWED_SOURCES stehen.
+GLPI_KB_SOURCE=glpi-kb
+
+# true:
+#   freigegebene GLPI-KB-Artikel können Auto-Replies auslösen.
+#
+# false:
+#   GLPI-KB wird nur für Recherche, RAG und Klassifizierung verwendet.
+GLPI_KB_AUTO_REPLY=true
+
+# Whitelist der GLPI-KNOWLEDGE-BASE-Kategorie-IDs.
+#
+# WICHTIG:
+# Das sind NICHT die GLPI-ITIL-/Ticketkategorie-IDs.
+#
+# Mehrere Werte:
+#   1,4,7
+GLPI_KB_AUTO_REPLY_CATEGORY_IDS=1
+
+
+###############################################################################
+# 14. HUMAN-IN-THE-LOOP / LERNEN
+###############################################################################
+
+# Menschlich bestätigte/korrigierte Kategorieentscheidungen als Lernbeispiele
+# verwenden.
+#
+# Die KI lernt NICHT automatisch aus ihren eigenen Entscheidungen.
+LEARNING_ENABLED=true
+
+# Maximale Anzahl gespeicherter Lernbeispiele.
+LEARNING_MAX_EXAMPLES=500
+
+# Maximale Anzahl Beispiele je Kategorie, die in einen KI-Prompt übernommen werden.
+LEARNING_EXAMPLES_PER_CATEGORY=5
+
+
+###############################################################################
+# 15. KOMMUNIKATION MIT ENDNUTZERN
+###############################################################################
+
+# Auto-Reply-KBs müssen zu Sprache und Kommunikationsstil passen.
+COMMUNICATION_LANGUAGE=de-DE
+COMMUNICATION_STYLE=formal
+
+# Wird vor den freigegebenen KB-Inhalt gesetzt.
+COMMUNICATION_SALUTATION=Guten Tag,
+
+# Abschluss der Antwort.
+COMMUNICATION_CLOSING=Mit freundlichen Grüßen
+COMMUNICATION_SIGNATURE=IT-Service
+
+
+###############################################################################
+# 16. EXTERNER BETRIEBSKONTEXT
+###############################################################################
+
+# Globaler Schalter für:
+# - Changes
+# - Major Incidents
+# - Benutzer/Geräte
+# - Uptime Kuma
+CONTEXT_ENABLED=true
+
+# Gemeinsames Timeout für Kontextabfragen.
+CONTEXT_TIMEOUT=12s
+
+# Minimale deterministische Relevanz zwischen Ticket und Incident/Outage.
+CONTEXT_RELEVANCE_MIN_SCORE=0.20
+
+# Wenn eine aktivierte Kontextquelle fehlschlägt:
+# true = Auto-Reply sicherheitshalber blockieren.
+CONTEXT_BLOCK_AUTO_REPLY_ON_ERRORS=true
+
+# Bei relevantem Major Incident / zentraler Störung:
+# true = individuelle Standard-Auto-Replies blockieren.
+CONTEXT_BLOCK_AUTO_REPLY_ON_INCIDENT=true
+
+
+###############################################################################
+# 17. GLPI CHANGE CALENDAR
+###############################################################################
+
+CHANGE_CALENDAR_ENABLED=true
+
+# High-Level-API-Route.
+# Wird gegen /api.php/doc.json geprüft.
+GLPI_CHANGE_PATH=/Assistance/Change
+
+# Optionaler GLPI-Filter.
+GLPI_CHANGE_FILTER=
+
+# Maximal geladene Changes.
+GLPI_CHANGE_LIMIT=100
+
+# Vergangener Zeitraum, der für Tickets berücksichtigt wird.
+CHANGE_LOOKBACK=72h
+
+# Zukünftiger Zeitraum.
+CHANGE_LOOKAHEAD=24h
+
+
+###############################################################################
+# 18. MAJOR INCIDENTS
+###############################################################################
+
+# false = Funktion vollständig deaktiviert.
+MAJOR_INCIDENTS_ENABLED=false
+
+# Muss bei aktiviertem Major-Incident-Modus bewusst gesetzt werden.
+#
+# Beispiel hängt von der eigenen GLPI-Struktur ab.
+# Gegen /api.php/doc bzw. die GLPI-Filtersemantik prüfen.
+GLPI_MAJOR_INCIDENT_FILTER=
+
+GLPI_MAJOR_INCIDENT_LIMIT=20
+
+
+###############################################################################
+# 19. BENUTZER -> GERÄT / ASSET-KONTEXT
+###############################################################################
+
+# Zusätzlich zu direkt am Ticket verknüpften Assets die dem Requester
+# zugeordneten Geräte suchen.
+USER_DEVICE_CONTEXT_ENABLED=true
+
+# Eine oder mehrere Asset-Routen.
+# Mehrere Werte ggf. komma-separiert, sofern vom Agent unterstützt.
+GLPI_USER_DEVICE_PATHS=/Assets/Computer
+
+# {{user_id}} wird durch die jeweilige GLPI-Requester-ID ersetzt.
+#
+# Nicht durch eine feste Benutzer-ID ersetzen.
+GLPI_USER_DEVICE_FILTER_TEMPLATE=user.id=={{user_id}}
+
+GLPI_USER_DEVICE_LIMIT=20
+
+
+###############################################################################
+# 20. UPTIME KUMA
+###############################################################################
+
+# false = keine Uptime-Kuma-Abfragen.
+UPTIME_KUMA_ENABLED=false
+
+UPTIME_KUMA_URL=https://uptime.example.com
+
+# Mögliche Modi:
+#
+#   metrics
+#     Authentifizierter Prometheus-/metrics-Endpunkt.
+#     Für interne Systeme empfohlen.
+#
+#   status_page
+#     Veröffentlichte Uptime-Kuma-Statusseiten.
+#
+UPTIME_KUMA_MODE=metrics
+
+# Nur für metrics erforderlich.
+# Bei deaktiviertem Uptime Kuma am besten leer lassen.
+UPTIME_KUMA_API_KEY=<SECRET>
+
+# Nur für status_page erforderlich.
+# Mehrere Slugs komma-separiert:
+#   it-services,network,applications
+UPTIME_KUMA_STATUS_PAGES=it-services
+
+UPTIME_KUMA_TIMEOUT=10s
+
+# Maximal an den Agenten übergebene aktuelle Probleme.
+UPTIME_KUMA_MAX_ISSUES=20
+
+# Maintenance-Zustände ebenfalls als Kontext berücksichtigen.
+UPTIME_KUMA_INCLUDE_MAINTENANCE=true
+
+
+###############################################################################
+# 21. POLICY-GATES
+###############################################################################
+
+# Automatische Kategorisierung grundsätzlich zulassen.
+AUTO_CATEGORY=true
+
+# Automatische Endnutzerantworten grundsätzlich zulassen.
+#
+# DRY_RUN=true verhindert trotzdem das Schreiben.
+AUTO_REPLY=true
+
+# Minimale KI-Confidence für Kategorieempfehlungen.
+CATEGORY_CONFIDENCE=0.70
+
+# Minimale KI-Confidence für Lösungsvorschläge.
+#
+# Zusätzlich gelten u. a.:
+# - Knowledge-Evidenz
+# - Source Policy
+# - Auto-Reply-Freigabe der KB
+# - kein vorhandenes Followup
+# - Kontext-/Incident-Regeln
+REPLY_CONFIDENCE=0.70
+
+
+###############################################################################
+# 22. WORKER / QUEUE
+###############################################################################
+
+# Maximale Anzahl wartender Ticketjobs.
+QUEUE_SIZE=256
+
+# Parallele Ticket-Worker.
+#
+# Darf größer als OLLAMA_MAX_CONCURRENT sein:
+# Ollama wird separat durch seine eigene Parallelitätsgrenze geschützt.
+WORKERS=2