Skip to content

Jafar

Projekt-Repository für Predictive Analytics im Modul 63184 "Fachpraktikum Softwareentwicklung mit Methoden der Künstlichen Intelligenz" an der FernUniversität Hagen im Sommersemester 2025.

Klassifikation der queue aus subject und body des Customer IT Support - Ticket Datasets von Tobias Bück.

Production

Die Software läuft auf einem Hetzner-VPS. Folgende URLs führen mit den passenden Zugangsdaten zu den Live-Services:

Der Code wird auf Github verwaltet:

Für die kollaborative Projektarbeit wurden außerdem folgende Services benutzt:

  • die Linear-Instanz für das Projektmanagement unter https://linear.app/pre-ana
  • die Projekt-interne Nextcloud unter https://nextcloud.jafar.live

Lokale Ausführung unter Nutzung der gehosteten Services

Die Software in diesem Repository kann unter Nutzung der passenden Umgebungsvariablen lokal ausgeführt werden und dabei die online gehosteten Services (Mails, Storage, Ticketsystem) benutzen. Die benötigten Variablennamen finden sich in .env.example, eine Liste mit vollständigen Key-Value-Paaren wird auf vertraulichem Wege bereitgestellt.

Verwendung von docker compose

Der einfachste und auch auf unserem Server genutzte Weg für die Ausführung der Software führt über das entwickelte Dockerfile und die docker-compose.yml. Der Build erfordert eine .env_docker-Datei, die aus der inkludierten .env_docker.example durch Umbenennung und Befüllung mit den richtigen Values erstellt werden kann. Bei Projektübergabe stellen wir auch diese Datei vollständig bereit. Liegt sie im Repo, lässt sich der Container bauen und starten:

docker compose build        # Build des Images
docker compse up -d         # Starten des Containers

Manuelle Ausführung

Die Ausführung der Software stützt sich auf zwei zentrale Einstiegspunkte:

  • streamlit run .\src\dashboard\app.py startet das Dashboard
  • python .\srv\worker.py startet den Worker, der E-Mails abruft, KI-Modelle lädt und damit die Mails klassifiziert

Beide Services lassen sich getrennt voneinander starten und verwenden, solange die Umgebungsvariablen zu den externen Services passend konfiguriert sind.

Lokaler Nachhbau der gesamten Servicelandschaft

Die Konfigurationen der gesamten Servicelandschaft finden sich im Infrastruktur-Repo. Da der Betrieb zahlreiche Entscheidungen über den Einsatz (lokaler) Domains, DNS-Server, TLS-Verschlüsselung und entsprechende Anpassung der in der Anwendung verwendeten Umgebungsvariablen erfordert, kann unsere Installationanleitung leider nicht alle Eventualitäten abdecken. Unsere eigenen Entscheidungen wurden jedoch so gut wie möglich dokumentiert.

Software-Dokumentation

Die Funktion der einzelnen Bestandteile der Software wurde mit Hilfe von mkdocs dokumentiert.

Dazu gehören auch die befolgten Konventionen, der Aufbau des Environments und die Bedienung der Schnittstellen zu unseren Services.

Die direkt in unserer Software geschriebenen Docstrings wurden dazu mit Hilfe des Plugins mkdocstrings importiert.

Ein Build der vollständigen HTML-Seiten lässt sich im Verzeichnis docs/site über die dortige index.html mit dem Browser öffnen.

Developement

Die Entwicklung fand mit uv als Paketmanager statt und verwendet eine Virtuelle Umgebung mit Python 3.12. Sie lässt sich unter Windows mit uv erstellen, aktivieren und mit den in pyproject.toml bzw. uv.lock definierten Paketen installieren:

uv venv -p312             # Virtuelle Umgebung erstellen
.venv\Scripts\activate    # .venv aktivieren
uv sync                   # Pakete installieren

Für Anwender:innen von pip steht alternativ eine exportierte requirements.txt zur Verfügung, mit der sich in einer selbstgewählten Umgebung die passenden Abhängigkeiten installieren lassen:

pip install -r requirements.txt