readme Übersetzt

math-tutor/README.md

-# DER Tutor
+# Der Tutor
+
+Dies ist ein Tutor-Bot der auf dem digitalen Lehrwerk von Anselm Knebusch beruht.
+Es gibt 4 Modi.
+
+1. Ein Q&A-Modus in dem man Fragen zum den Inhalten des Skript stellen kann.
+2. Ein offener Tutormodus in dem man eigene Fragen stellen kann und diese mit dem Bot besprechen kann
+3. Ein geschlossener Task Modus in dem man Aufgaben aus dem Lehrwerk mit dem Tutorbot besprechn kann.
+4. Ein Sokrates Modus in dem man ein sokratischen Dialog zu einem Abschnitt aus dem Lehrwerk führen kann.
+
+Aktuell gibt es noch nicht zu allen Themen Material.
 
 ## Prequisits
 
-- Postgres-Database [Database (pgvector) setup]
-- sources folder with your markdown files structured with section, subsection and child
-- OpenAI endpoint
-- Ollama Instanz
+- Postgres-Datenbank [Einrichtung der Datenbank (pgvector)]
+- Ordner „sources“ mit Ihren Markdown-Dateien, strukturiert nach Abschnitten, Unterabschnitten und Unter-Unterabschnitten
+- OpenAI-Endpunkt
+- Ollama-Instanz
 
-if you want to use the task mode you need :
+Wenn Sie den Aufgabenmodus nutzen möchten, benötigen Sie:
 
-- task folder in sources with your tasks
-- `_subsection_map.yaml` as the topic-to-index map for section, subsection, or subsubsection references.
+- Ordner „tasks“ im Verzeichnis „sources“ mit Ihren Aufgaben
+- `_subsection_map.yaml` als Zuordnung von Themen zu Indizes für Verweise auf Abschnitte, Unterabschnitte oder Unter-Unterabschnitte.
 
-## Setup
+Übersetzt mit DeepL.com (kostenlose Version)
 
-Configurate the `backend/.env`-file based on the `backend/.env-example`. You can che following modes:
+## Setup
 
-- QA : Direct answer based on the retrieval
-- Tutor: Helps with tips on a task given by the user
-- Task: A mode where you can select from the list in the taskfolder and get help with this Task.
+Konfigurieren Sie die Datei `backend/.env` anhand der Datei `backend/.env-example`.
 
 Backend (Python):
 
@@ -56,24 +64,24 @@ pnpm run dev
 
 ### Task Deep Links
 
-You can open a task chat directly with URL query parameters:
+Sie können einen Aufgaben-Chat direkt über URL-Abfrageparameter öffnen:
 
 `/chat?orchestrator=task&file_id=<task_file_id>&task_id=<task_id>`
 
-Example:
+Beispiel:
 
 `http://localhost:5173/chat?orchestrator=task&file_id=abc-formel-anwenden&task_id=03`
 
-Notes:
+Hinweise:
 
-- `file_id` must match an existing task file id from the task catalog.
-- `task_id` must exist inside that file.
-- If the link is invalid, the frontend falls back to `/select-task`.
-- The task is not locked by deep link, so users can still switch tasks afterwards.
+- `file_id` muss mit der ID einer vorhandenen Aufgabendatei aus dem Aufgabenkatalog übereinstimmen.
+- `task_id` muss in dieser Datei vorhanden sein.
+- Ist der Link ungültig, weicht das Frontend auf `/select-task` aus.
+- Die Aufgabe wird durch den Deep Link nicht gesperrt, sodass Benutzer anschließend weiterhin zwischen Aufgaben wechseln können.
 
 ### Socratic Deep Links
 
-You can open a socratic chat directly with URL query parameters:
+Sie können einen Sokratischen Chat direkt über URL-Abfrageparameter öffnen:
 
 `/chat?orchestrator=socratic&topic_key=<topic_key>`
 
@@ -81,16 +89,16 @@ Example:
 
 `http://localhost:5173/chat?orchestrator=socratic&topic_key=klammerrechnung`
 
-Notes:
+Hinweise:
 
-- `topic_key` must match an existing socratic topic from the task catalog.
-- The links use normalized topic keys in the URL, and the app resolves them back to the catalog key.
-- The fallback `/select-socratic` page only shows the topic dropdown and start button.
-- If the link is invalid, the frontend falls back to `/select-socratic`.
-- The socratic dialog is not locked by deep link, so users can still switch topics afterwards.
+- `topic_key` muss mit einem vorhandenen Sokratischen Thema aus dem Aufgabenkatalog übereinstimmen.
+- Die Links verwenden normalisierte Themen-Schlüssel in der URL, und die App löst diese wieder in den Katalog-Schlüssel auf.
+- Die Fallback-Seite `/select-socratic` zeigt nur das Themen-Dropdown-Menü und die Start-Schaltfläche an.
+- Wenn der Link ungültig ist, weicht das Frontend auf `/select-socratic` aus.
+- Der Sokratische Dialog ist nicht durch einen Deep Link gesperrt, sodass Benutzer das Thema auch nachträglich noch wechseln können.
 
-To make it accessible over the network.
-Add the frontend- and backend-adress in the `backend/.env`-file in the frontend- and backend-folder. Use the following command to run the front- and backend.
+Um den Zugriff über das Netzwerk zu ermöglichen.
+Füge die Frontend- und Backend-Adressen in die Datei `backend/.env` im Frontend- und Backend-Ordner ein. Verwende den folgenden Befehl, um das Frontend und Backend auszuführen.
 
 ```powershell
 python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
@@ -99,23 +107,23 @@ pnpm run dev -- --host 0.0.0.0
 
 ### Frontend package manager policy (pnpm)
 
-- Required versions:
-  - Node.js: 22.x or newer
-  - pnpm: pinned via `math-tutor/frontend/package.json` (`packageManager`)
-- Lockfile policy:
-  - Commit `pnpm-lock.yaml`.
-  - Use `pnpm install --frozen-lockfile` in local CI-like checks and Docker builds.
-- Install-script policy (strict):
-  - Dependency build/install scripts are allowlisted.
-  - After adding/updating dependencies, run `pnpm approve-builds` and review what is allowed.
-  - Check blocked scripts with `pnpm ignored-builds`.
+- Erforderliche Versionen:
+  - Node.js: 22.x oder neuer
+  - pnpm: über `math-tutor/frontend/package.json` (`packageManager`) festgelegt
+- Richtlinie für die Lockdatei:
+  - `pnpm-lock.yaml` festschreiben.
+  - Verwende `pnpm install --frozen-lockfile` bei lokalen CI-ähnlichen Prüfungen und Docker-Builds.
+- Richtlinie für Installationsskripte (streng):
+  - Skripte zum Erstellen/Installieren von Abhängigkeiten werden auf die Whitelist gesetzt.
+  - Führe nach dem Hinzufügen/Aktualisieren von Abhängigkeiten `pnpm approve-builds` aus und überprüfe, was zugelassen ist.
+  - Überprüfe blockierte Skripte mit `pnpm ignored-builds`.
 
 ### Vite Proxy (Development)
 
-The frontend now supports a dev proxy for API calls:
+Das Frontend unterstützt nun einen Dev-Proxy für API-Aufrufe:
 
-- Frontend requests `/api/...` to Vite
-- Vite forwards `/api` to the backend target
+- Das Frontend sendet Anfragen an `/api/...` an Vite
+- Vite leitet `/api` an das Backend-Ziel weiter
 
 Optional in `math-tutor/frontend/.env`:
 
@@ -139,18 +147,18 @@ cd math-tutor/docker
 docker compose up --build -d
 ```
 
-Open in browser:
+In browser öffnen:
 
 - `http://<HOST>:80`
 
-Notes:
+Hinweise:
 
-- Nginx serves the built frontend and proxies `/api` to backend (`http://backend:8000`).
-- Keep frontend API calls relative (`/api/...`) for this setup.
+- Nginx stellt das integrierte Frontend bereit und leitet Anfragen an `/api` an das Backend weiter (`http://backend:8000`).
+- Halten Sie die API-Aufrufe im Frontend in dieser Konfiguration relativ (`/api/...`).
 
 ## Database (pgvector) setup
 
-Ensure `POSTGRES_URL` and embedding env vars are in `backend/.env`:
+Stelle sicher, dass `POSTGRES_URL` und die anderen Umgebungsvariablen in `backend/.env` enthalten sind:
 
 ``` env
 POSTGRES_URL=postgresql://user:pass@host:5432/db
@@ -159,7 +167,7 @@ OPENAI_API_KEY=...
 OPENAI_EMBED_MODEL=...
 ```
 
-Create the Postgres database before running init.
+Erstellen Sie die Postgres-Datenbank, bevor Sie „init“ ausführen.
 
 Init DB schema:
 
@@ -169,7 +177,7 @@ cd math-tutor/backend
 python -m scripts.retrieval_cli init-db
 ```
 
-Ingest markdown docs (expects `markdown/sections`, `markdown/subsections`, `markdown/childs`):
+Markdown docs einbetten (expects `markdown/sections`, `markdown/subsections`, `markdown/childs`):
 
 ```powershell
 cd math-tutor/backend
@@ -185,32 +193,24 @@ cd math-tutor/backend
 python -m scripts.retrieval_cli query --q "Was ist eine Teilmenge?" --k 8 --expand
 ```
 
-## Generate Socratic Chats
-
-```powershell
-cd math-tutor/backend
-.\.venv\Scripts\Activate.ps1
-python -m scripts.generate_socratic_chats --source-root sources/lecture_script --output sources/inital_socratic_prompt/initial_prompts.yaml
-```
-
 ## Configuration
 
-Differend Orchestrators:
+Verschiedene Orchestrators:
 
 - Edit `math-tutor/backend/app/api/chat.py` and update `SYSTEM_PROMPT`.
 
 Retrieval settings:
 
-- Frontend request parameters live in `math-tutor/frontend/src/pages/App.tsx`:
+- Frontend-Anfrageparameter befinden sich in `math-tutor/frontend/src/pages/App.tsx`:
   - `k`
   - `expand_links`
   - `neighbor_expand`
-- Backend defaults are in `math-tutor/backend/app/api/retrieval.py` (`QueryRequest`).
-- Core retrieval logic is in `math-tutor/backend/app/services/vector_store.py` (`retrieve`).
+- Die Backend-Standardeinstellungen sind enthalten `math-tutor/backend/app/api/retrieval.py` (`QueryRequest`).
+- Die Kernlogik für das Abrufen ist vorhanden `math-tutor/backend/app/services/vector_store.py` (`retrieve`).
 
 ## Testing
 
-currently there a multiple test to test some components seperatly. Check the test files for specific calling. Here are some example calls.
+Derzeit gibt es mehrere Tests, um bestimmte Komponenten separat zu prüfen. Die genauen Aufrufe finden Sie in den Testdateien. Hier sind einige Beispielaufrufe.
 
 ```powershell
 python -m test.hint_test --chat-id draft_session_mlgmxxzc_avmjfb
@@ -223,3 +223,11 @@ python -m test.math_intent_test --input "Integrate x^2" --input "Was ist 2+2?"
 
 python -m test.decision_test --chat-id draft_session_mlgmxxzc_avmjfb
 ```
+
+## Generate Socratic Chats
+
+```powershell
+cd math-tutor/backend
+.\.venv\Scripts\Activate.ps1
+python -m scripts.generate_socratic_chats --source-root sources/lecture_script --output sources/inital_socratic_prompt/initial_prompts.yaml
+```