Schula

Schula ist ein modulares Framework zur Analyse und Bewertung von Schülerantworten basierend auf einer Musterlösung (Erwartungshorizont). Es verwendet Language Models (LLMs), um Textsegmente von Schülerantworten den entsprechenden Punkten der Musterlösung zuzuordnen.

Features

• Pipeline-basierter Aufbau mit klar definierten Modulen
• Integration von LLMs für semantisches Matching
• Nutzung von Tools wie OCR, Zeilendetektion, Strikethrough-Erkennung
• Web-GUI über Streamlit

Ausführung

• Starte die Webanwendung mit:

streamlit run src/main_app.py

• Alternativ kann eine Pipeline direkt gestartet werden:

python3 src/main.py

Beispiel-Anwendung

streamlit run src/main_app.py

Die Anwendung lässt sich lokal starten und bietet eine visuelle Benutzeroberfläche zur Interaktion mit dem Dokumenten-Parser und dem LLM-Modul.

Installation

Das Projekt kann mit dem folgenden Befehl installiert werden:

git clone https://github.com/DominikHommer/Schula
cd schula
pip install -r requirements.txt

Hinweis: Einige Pakete (z. B. ultralytics, tensorflow) müssen zusätzlich manuell installiert werden. Siehe Abschnitt Anforderungen.

Projektstruktur

schula/
├── src/
│   ├── main_app.py               # Einstiegspunkt für die Streamlit-App
│   ├── app.py                    # Alternativer App-Einstieg (veraltet oder Headless)
│   ├── app_v2.py                 # Experimentelle Streamlit-Version
│   ├── libs/                     # LLM-Clients, Architektur, Hilfsfunktionen
│   │   ├── language_client.py
│   │   ├── file_helper.py
│   │   ├── Architecture.md       # (ehemalig, Inhalte nun in README integriert)
│   ├── modules/                  # Verarbeitungsmodule und zentrale Komponenten
│   │   ├── red_remover.py
│   │   ├── text_recognizer.py
│   │   ├── strikethrough_cleaner.py
│   │   ├── horizontal_cutter.py
│   │   ├── horizontal_cutter_line_detect.py
│   │   ├── line_cropper.py
│   │   ├── line_denoiser.py
│   │   ├── line_prepare_recognizer.py
│   │   ├── structured_document_parser.py  # CV-Pipeline Einstiegspunkt
│   │   ├── llm_text_extraction.py         # LLM-Zuordnungsschicht
│   │   ├── module_base.py
│   │   ├── llm_module_base.py
│   ├── pipelines/                # Konkrete Verarbeitungspipelines
│   │   ├── pipeline.py
│   │   ├── llm_pipeline.py
│   │   ├── llm_extractor.py
│   │   ├── pdf_processor.py
│   │   ├── student_exam_extractor.py
│   │   ├── cv_pipeline.py
│   ├── tests/                    # Unit- und Integrationstests

Architektur

Die Architektur von Schula folgt einem modularen, gekapselten Aufbau, der stark auf einen klar definierten LLM-Lifecycle setzt. Jede Einheit der Verarbeitung (ob CV oder LLM) kapselt ihre eigenen Schritte und kommuniziert nur über definierte Schnittstellen:

• CV-Pipeline: Verantwortlich für alle bildverarbeitenden Schritte – von der PDF-Zerlegung über Segmentierung bis zur OCR. Ergebnis sind strukturierte Texteinheiten.

• LLMClient (in libs/): Vermittelt zwischen LLMs und Modulen

  • Initialisiert LLMs
  • Führt Tool-/Agent-Schleifen aus
  • Gibt ein Result zurück

• LLMPipeline (in pipelines/): Organisiert die Zusammenarbeit

  • Erstellt und verwaltet LLMClient
  • Übergibt ihn an Module

• Module (in modules/):

  • Nutzen LLMClient
  • Definieren ihre Prompts und Tools
  • Führen ihren eigenen Lifecycle aus (Init → Loop → Result)

1. Modul-Basisklassen (module_base.py & llm_module_base.py)

• module_base.py: Definiert eine abstrakte Basisklasse für alle Verarbeitungsschritte (OCR, Bildvorverarbeitung etc.) mit einer einheitlichen run()-Schnittstelle.
• llm_module_base.py: Erweitert die Basisklasse um LLM-spezifische Funktionalität wie Prompt-Erstellung, Model-Interaktion und strukturierte Ausgabe via Pydantic.

2. LLMClient (src/libs/language_client.py)

• Verwaltet die gesamte Kommunikation mit externen Language Models (z. B. OpenAI, Groq, HuggingFace).

• Jedes Modul, das LLMs verwendet, startet einen eigenen LLM-Lifecycle:

  • Initialisierung
  • Tool-/Agent-Loop mit interaktiver Verarbeitung
  • Ergebnis-Rückgabe

3. LLMPipeline (src/pipelines/llm_pipeline.py)

• Zentraler Koordinator für LLM-basierte Module.
• Ruft relevante Extraktoren auf (z. B. llm_extractor, student_exam_extractor).
• Nutzt language_client zur Abwicklung der Prompt-Kommunikation.

4. CV-Pipeline (modules/structured_document_parser.py + pipelines/pdf_processor.py + pipelines/cv_pipeline.py)

• Diese Pipeline übernimmt alle bildbasierten Vorverarbeitungsschritte.

• Typische Schritte:

  • Laden und Rendern von PDF-Seiten als Bilder
  • Entfernen von roten Markierungen (red_remover.py)
  • Entfernen von Durchstreichungen (strikethrough_cleaner.py)
  • Horizontales Schneiden in Zeilen (horizontal_cutter.py, horizontal_cutter_line_detect.py)
  • Zuschneiden und Entstören von Zeilenbildern (line_cropper.py, line_denoiser.py)
  • OCR mit text_recognizer.py
  • Gruppierung und Strukturierung der Textergebnisse

• Ergebnis: Strukturierte, bereinigte Texteinheiten zur Übergabe an die LLM-Pipeline

5. Weitere Pipelines (src/pipelines)

• llm_extractor.py: Führt LLM-Analyse durch und parst strukturierte Ergebnisse.
• student_exam_extractor.py: Extrahiert relevante Abschnitte aus Schülerantworten.

6. Module (src/modules)

• Alle OCR-, Bildverarbeitungs- und Preprocessing-Module erben von ModuleBase.
• LLM-gestützte Module erben von LLMModuleBase und definieren eigene Prompts sowie erwartete Antwortformate.
• Der modulare Aufbau erlaubt einfache Erweiterbarkeit und Wiederverwendung.

Typischer Ablauf

1. PDF-Upload: Ein Dokument mit Musterlösung und Schülerantwort wird geladen.
2. Preprocessing: Entfernen von Linien, Durchstreichungen, Farbinformationen.
3. OCR: Erkennung der Textinhalte aus den Segmenten.
4. Segmentierung: Zerlegung in Textblöcke (z. B. Aufgaben, Lösungen, Randnotizen).
5. LLM Matching: Über Pydantic-Modelle und Prompts werden die Textsegmente den Punkten aus dem Erwartungshorizont zugeordnet.
6. Darstellung: Ergebnisse und Zuweisungen werden über die Streamlit-Oberfläche visualisiert.

Anforderungen

• Python < 3.13 wird empfohlen

• Zusätzliche manuelle Installation nötig:

  • ultralytics==8.3.115
  • tensorflow==2.19.0

Daten

Bitte wenden Sie sich für Daten an einen der genannten Autoren

Linting & Tests

Linting

• Ausführen von pylint src/ zur statischen Codeanalyse
• Dokumentation: https://docs.pylint.org/
• Optional: Typprüfung mit mypy src/
• Dokumentation: https://mypy.readthedocs.io/en/latest/getting_started.html

Unit Tests

• Jedes Modul sollte durch Unit-Tests abgedeckt sein
• Pipelines sollten sinnvoll getestet werden
• Tests befinden sich im Ordner tests, Mockdaten unter tests/fixtures
• Tests ausführen mit (in root Ordner):

python -m unittest

Lizenz

Dieses Projekt steht unter der GNU General Public License v3.0.

Autoren: Dominik Hommer, Benedikt Veith, Edmond Skender, Bastian Schwarz, Nils Poethkow

Copyright (C) 2025 Dominik Hommer, Benedikt Veith, Edmond Skender, Bastian Schwarz, Nils Poethkow

Dieses Programm ist freie Software: Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren – entweder gemäß Version 3 der Lizenz oder (nach Ihrer Wahl) jeder späteren Version.

Dieses Programm wird in der Hoffnung verbreitet, dass es nützlich sein wird, aber OHNE JEDE GEWÄHRLEISTUNG – sogar ohne die implizite Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK. Siehe die GNU General Public License für weitere Details.

Sie sollten eine Kopie der GNU General Public License zusammen mit diesem Programm erhalten haben. Wenn nicht, siehe https://www.gnu.org/licenses/.