exam_translator¶

`academic_doc_generator.exam_translator` ¶

Exam Translator package for converting LaTeX exam documents from German to English.

`split_latex_exam_into_sections(latex_content, verbose=False)` ¶

Teilt ein LaTeX-Dokument in Präambel, Fragen und Postamble auf.

Ignoriert auskommentierte \begin{questions} und \end{questions} Befehle.

Parameters:

Name	Type	Description	Default
`latex_content`	`str`	Der komplette LaTeX-Quelltext.	required
`verbose`	`bool`	Wenn True, werden zusätzliche Informationen ausgegeben.	`False`

Returns:

Type	Description
`str`	Tuple aus (preamble, questions_list, postamble):
`list[str]`	preamble: Der Teil vor \begin{questions} inklusive \begin{questions}
`str`	questions_list: Liste der einzelnen Fragen, die jeweils mit \question beginnen
`tuple[str, list[str], str]`	postamble: Der Teil ab \end{questions} inklusive \end{questions}

Example

preamble, questions, postamble = split_latex_exam_into_sections(latex_text) len(questions) 5

Source code in src/academic_doc_generator/exam_translator/translator.py

def split_latex_exam_into_sections(
    latex_content: str, verbose: bool = False
) -> tuple[str, list[str], str]:
    """Teilt ein LaTeX-Dokument in Präambel, Fragen und Postamble auf.

    Ignoriert auskommentierte \\begin{questions} und \\end{questions} Befehle.

    Args:
        latex_content: Der komplette LaTeX-Quelltext.
        verbose: Wenn True, werden zusätzliche Informationen ausgegeben.

    Returns:
        Tuple aus (preamble, questions_list, postamble):
        - preamble: Der Teil vor \\begin{questions} inklusive \\begin{questions}
        - questions_list: Liste der einzelnen Fragen, die jeweils mit \\question beginnen
        - postamble: Der Teil ab \\end{questions} inklusive \\end{questions}

    Example:
        >>> preamble, questions, postamble = split_latex_exam_into_sections(latex_text)
        >>> len(questions)
        5
    """
    # Finde den Anfang der Questions-Umgebung (nicht am Zeilenanfang auskommentiert)
    # Nutze [^\n%]*?, um sicherzustellen, dass kein % vor \begin{questions} steht.
    match = re.search(r"(?m)^(?![ \t]*%)[^\n%]*?\\begin\{questions\}", latex_content)

    if not match:
        raise ValueError("Keine \\begin{questions} Umgebung gefunden!")

    # Präambel ist alles bis einschließlich \begin{questions}
    preamble_end = match.end()
    preamble = latex_content[:preamble_end]

    # Rest des Dokuments
    remaining = latex_content[preamble_end:]

    # Finde das Ende der Questions-Umgebung (nicht am Zeilenanfang auskommentiert)
    end_match = re.search(r"(?m)^(?![ \t]*%)[^\n%]*?\\end\{questions\}", remaining)

    if not end_match:
        raise ValueError("Keine \\end{questions} Umgebung gefunden!")

    # Nur der Teil zwischen \begin{questions} und \end{questions}
    questions_content = remaining[: end_match.start()]
    postamble = remaining[end_match.start() :]  # \end{questions} und alles danach

    # Teile in einzelne Questions auf (beginnend mit \question)
    # Nutze einen lookahead, um \question als Delimiter zu verwenden,
    # aber nur wenn es nicht am Zeilenanfang auskommentiert ist.
    # [ \t]* erlaubt eingerückte Fragen.
    question_pattern = r"(?m)^(?![ \t]*%)[ \t]*(?=\\question)"
    questions_raw = re.split(question_pattern, questions_content)

    # Entferne leere Strings und Whitespace-only Einträge
    questions = [q.strip() for q in questions_raw if q.strip()]

    return preamble, questions, postamble

`translate_latex_exam(input_path, llm_client=None, output_path=None, verbose=False)` ¶

Übersetzt eine komplette LaTeX-Klausur von Deutsch nach Englisch.

Diese Funktion: 1. Liest die LaTeX-Datei ein 2. Teilt sie in Präambel und einzelne Fragen auf 3. Übersetzt jeden Abschnitt einzeln mit dem LLM 4. Fügt alle übersetzten Teile wieder zusammen 5. Speichert das Ergebnis mit Suffix "_engl"

Parameters:

Name	Type	Description	Default
`input_path`	`str \| Path`	Pfad zur deutschen LaTeX-Klausur.	required
`llm_client`	`LLMClient`	LLMClient-Instanz. Wenn None, wird eine neue erstellt.	`None`
`output_path`	`str \| Path`	Pfad für die englische Ausgabe. Wenn None, wird automatisch der Eingabepfad mit Suffix "_engl" verwendet.	`None`
`verbose`	`bool`	Wenn True, werden Debug-Informationen ausgegeben.	`False`

Returns:

Type	Description
`str`	Pfad zur gespeicherten englischen LaTeX-Datei.

Raises:

Type	Description
`FileNotFoundError`	Wenn die Eingabedatei nicht existiert.
`ValueError`	Wenn die LaTeX-Struktur nicht korrekt ist.

Example

from llm_client import LLMClient client = LLMClient() output = translate_latex_exam("KIKlausurSoSe25_1.tex", client) print(output) KIKlausurSoSe25_1_engl.tex

Source code in src/academic_doc_generator/exam_translator/translator.py

def translate_latex_exam(
    input_path: str | Path,
    llm_client: LLMClient = None,
    output_path: str | Path = None,
    verbose: bool = False,
) -> str:
    """Übersetzt eine komplette LaTeX-Klausur von Deutsch nach Englisch.

    Diese Funktion:
    1. Liest die LaTeX-Datei ein
    2. Teilt sie in Präambel und einzelne Fragen auf
    3. Übersetzt jeden Abschnitt einzeln mit dem LLM
    4. Fügt alle übersetzten Teile wieder zusammen
    5. Speichert das Ergebnis mit Suffix "_engl"

    Args:
        input_path: Pfad zur deutschen LaTeX-Klausur.
        llm_client: LLMClient-Instanz. Wenn None, wird eine neue erstellt.
        output_path: Pfad für die englische Ausgabe. Wenn None, wird automatisch
                    der Eingabepfad mit Suffix "_engl" verwendet.
        verbose: Wenn True, werden Debug-Informationen ausgegeben.

    Returns:
        Pfad zur gespeicherten englischen LaTeX-Datei.

    Raises:
        FileNotFoundError: Wenn die Eingabedatei nicht existiert.
        ValueError: Wenn die LaTeX-Struktur nicht korrekt ist.

    Example:
        >>> from llm_client import LLMClient
        >>> client = LLMClient()
        >>> output = translate_latex_exam("KIKlausurSoSe25_1.tex", client)
        >>> print(output)
        KIKlausurSoSe25_1_engl.tex
    """
    # Erstelle LLMClient falls nicht vorhanden
    if llm_client is None:
        llm_client = LLMClient()
        print(f"✓ LLM: {llm_client.api_choice} / {llm_client.llm}")

    # Konvertiere zu Path-Objekten
    input_path = Path(input_path)

    if not input_path.exists():
        raise FileNotFoundError(f"Datei nicht gefunden: {input_path}")

    # Bestimme Output-Pfad
    if output_path is None:
        stem = input_path.stem  # Dateiname ohne Endung
        suffix = input_path.suffix  # .tex
        output_path = input_path.parent / f"{stem}_engl{suffix}"
    else:
        output_path = Path(output_path)

    print(f"\n📄 Lese LaTeX-Datei: {input_path}")

    # Lese Input-Datei
    with open(input_path, encoding="utf-8") as f:
        latex_content = f.read()

    print("✂️  Teile Dokument in Abschnitte...")

    # Teile in Abschnitte
    preamble, questions, postamble = split_latex_exam_into_sections(latex_content, verbose)

    print(f"   • Präambel: {len(preamble)} Zeichen")
    print(f"   • Anzahl Fragen: {len(questions)}")
    print(f"   • Postamble: {len(postamble)} Zeichen")

    # Übersetze Präambel
    print("\n🌍 Übersetze Präambel...")
    translated_preamble = translate_preamble_to_english(preamble, llm_client, verbose=verbose)

    # Übersetze jede Frage einzeln
    print(f"\n🌍 Übersetze {len(questions)} Fragen...")
    translated_questions = []

    for i, question in enumerate(questions, start=1):
        print(f"   [{i}/{len(questions)}] Übersetze Frage {i}...")
        translated = translate_question_to_english(question, llm_client, verbose=verbose)
        translated_questions.append(translated)

    # Füge alles zusammen
    print("\n🔗 Füge übersetzte Abschnitte zusammen...")

    # Stelle sicher, dass Questions mit Newline beginnen
    questions_text = "\n\n".join(translated_questions)

    translated_content = f"{translated_preamble}\n\n" f"{questions_text}\n\n" f"{postamble}"

    # Speichere Ergebnis
    print(f"\n💾 Speichere englische Version: {output_path}")

    with open(output_path, "w", encoding="utf-8") as f:
        f.write(translated_content)

    print("✅ Übersetzung abgeschlossen!")
    print(f"   Original: {input_path}")
    print(f"   Übersetzt: {output_path}")

    return str(output_path)

`translate_preamble_to_english(preamble, llm_client, verbose=False)` ¶

Übersetzt die Präambel (Header, Anweisungen) von Deutsch nach Englisch.

Parameters:

Name	Type	Description	Default
`preamble`	`str`	Der Präambel-Teil des LaTeX-Dokuments.	required
`llm_client`	`LLMClient`	LLMClient-Instanz für API-Zugriff.	required
`verbose`	`bool`	Wenn True, werden Debug-Informationen ausgegeben.	`False`

Returns:

Type	Description
`str`	Die übersetzte Präambel.

Source code in src/academic_doc_generator/exam_translator/translator.py

def translate_preamble_to_english(
    preamble: str, llm_client: LLMClient, verbose: bool = False
) -> str:
    """Übersetzt die Präambel (Header, Anweisungen) von Deutsch nach Englisch.

    Args:
        preamble: Der Präambel-Teil des LaTeX-Dokuments.
        llm_client: LLMClient-Instanz für API-Zugriff.
        verbose: Wenn True, werden Debug-Informationen ausgegeben.

    Returns:
        Die übersetzte Präambel.
    """
    # Maskiere Kommentare vor der Übersetzung
    masked_text, comment_map = mask_comments(preamble)

    prompt = build_prompt(PromptTemplate.TRANSLATE_PREAMBLE, text=masked_text)

    messages = [{"role": "user", "content": prompt}]
    translated = llm_client.chat_completion(messages)

    if verbose:
        print(f"\n{'='*60}")
        print("PREAMBLE TRANSLATED")
        print(f"Länge Preamble: {len(preamble)}, Länge translated Preamble: {len(translated)}")
        if len(translated) < len(preamble) - 500:
            print(translated)
        print(f"{'='*60}\n")

    # Stelle Kommentare wieder her
    return unmask_comments(translated, comment_map).strip()

`translate_question_to_english(question_text, llm_client, verbose=False)` ¶

Übersetzt einen einzelnen Frage-Abschnitt von Deutsch nach Englisch.

Parameters:

Name	Type	Description	Default
`question_text`	`str`	Der LaTeX-Code einer einzelnen Frage (beginnt mit \question).	required
`llm_client`	`LLMClient`	LLMClient-Instanz für API-Zugriff.	required
`verbose`	`bool`	Wenn True, werden Debug-Informationen ausgegeben.	`False`

Returns:

Type	Description
`str`	Der übersetzte LaTeX-Code der Frage.

Example

client = LLMClient() translated = translate_question_to_english(question, client)

Source code in src/academic_doc_generator/exam_translator/translator.py

def translate_question_to_english(
    question_text: str, llm_client: LLMClient, verbose: bool = False
) -> str:
    """Übersetzt einen einzelnen Frage-Abschnitt von Deutsch nach Englisch.

    Args:
        question_text: Der LaTeX-Code einer einzelnen Frage (beginnt mit \\question).
        llm_client: LLMClient-Instanz für API-Zugriff.
        verbose: Wenn True, werden Debug-Informationen ausgegeben.

    Returns:
        Der übersetzte LaTeX-Code der Frage.

    Example:
        >>> client = LLMClient()
        >>> translated = translate_question_to_english(question, client)
    """
    # Maskiere Kommentare vor der Übersetzung
    masked_text, comment_map = mask_comments(question_text)

    prompt = build_prompt(PromptTemplate.TRANSLATE_QUESTION, text=masked_text)

    messages = [{"role": "user", "content": prompt}]
    translated = llm_client.chat_completion(messages)

    if verbose:
        print(f"\n{'='*60}")
        print("ORIGINAL:")
        print(question_text[:200] + "...")
        print(f"\n{'='*60}")
        print("TRANSLATED:")
        print(translated[:200] + "...")
        print(f"{'='*60}\n")

    # Stelle Kommentare wieder her
    return unmask_comments(translated, comment_map).strip()

exam_translator¶

academic_doc_generator.exam_translator ¶

split_latex_exam_into_sections(latex_content, verbose=False) ¶

translate_latex_exam(input_path, llm_client=None, output_path=None, verbose=False) ¶

translate_preamble_to_english(preamble, llm_client, verbose=False) ¶

translate_question_to_english(question_text, llm_client, verbose=False) ¶

`academic_doc_generator.exam_translator` ¶

`split_latex_exam_into_sections(latex_content, verbose=False)` ¶

`translate_latex_exam(input_path, llm_client=None, output_path=None, verbose=False)` ¶

`translate_preamble_to_english(preamble, llm_client, verbose=False)` ¶

`translate_question_to_english(question_text, llm_client, verbose=False)` ¶