Skip to content
GitLab
Commit cacb3882 authored by Kantz's avatar Kantz
Browse files

updated readme

parent 36f53281
Hide whitespace changes
Inline Side-by-side
math-tutor/README.md
View file @ cacb3882
# Der Tutor
Dies ist ein Tutor-Bot der auf dem digitalen Lehrwerk von Anselm Knebusch beruht.
Es gibt 4 Modi.
Dies ist ein Tutor-Bot für ein digitales Lehrwerk. Die App unterstützt aktüll vier Orchestratoren:
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.
1. `qa` für Fragen zu den Inhalten des Materials
2. `tutor` für einen offeneren Tutor-Dialog
3. `task` für Aufgaben aus dem Lehrwerk
4. `socratic` für einen sokratischen Dialog zu einem Thema
Aktuell gibt es noch nicht zu allen Themen Material.
Nicht für alle Themen ist bereits Material vorhanden.
## Prequisits
## Voraussetzungen
- Postgres-Datenbank [Einrichtung der Datenbank (pgvector)]
- Ordner „sources“ mit Ihren Markdown-Dateien, strukturiert nach Abschnitten, Unterabschnitten und Unter-Unterabschnitten
- OpenAI-Endpunkt
- Ollama-Instanz
- Python für das Backend
- Node.js 22.x oder neür für das Frontend
- pnpm in der Version aus `frontend/package.json`
- Eine Postgres-Datenbank mit `pgvector`
- Inhaltsdateien unter `backend/sources/lecture_script`
- Für `task` zusätzlich Aufgaben unter `backend/sources/tasks`
- Ein konfigurierter LLM-Provider über `LLM_PROVIDER`
- Ein konfigurierter Embedding-Provider über `EMBEDDING_PROVIDER`
Wenn Sie den Aufgabenmodus nutzen möchten, benötigen Sie:
Unterstützte LLM-Provider:
- 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.
- `openai`
- `gwdg`
- `mistral`
- `ollama`
Übersetzt mit DeepL.com (kostenlose Version)
Unterstützte Embedding-Provider:
- `sentence-transformer`
- `openai`
- `gwdg`
## Setup
Konfigurieren Sie die Datei `backend/.env` anhand der Datei `backend/.env-example`.
Konfiguriere zürst `backend/.env` anhand von `backend/.env-example`.
Backend (Python):
Backend:
``` powershell
```powershell
cd math-tutor/backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
Frontend (Vite):
Frontend:
``` powershell
```powershell
cd math-tutor/frontend
corepack enable
pnpm install --frozen-lockfile
```
## Run the app
## Wichtige Konfiguration
Backend-Variablen in `math-tutor/backend/.env`:
- `POSTGRES_URL`
- `FRONTEND_URL`
- `ORCHESTRATOR`
- `LLM_PROVIDER`
- `EMBEDDING_PROVIDER`
Je nach Provider werden weitere Variablen aus `backend/.env-example` benötigt, zum Beispiel:
- `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_CHAT_MODEL`
- `GWDG_BASE_URL`, `GWDG_API_KEY`, `GWDG_CHAT_MODEL`
- `MISTRAL_API_KEY`, `MISTRAL_CHAT_MODEL`
- `OLLAMA_URL`, `OLLAMA_MODEL`
Frontend-Variablen in `math-tutor/frontend/.env`:
- `VITE_FRONTEND_LANG`
- `VITE_SHOW_CHATS_BUTTON`
- optional `VITE_API_BASE_URL` für den Dev-Proxy
Backend (Python):
## Anwendung starten
Das Backend führt beim Start Readiness-Checks, Datenbankinitialisierung für LLM-Quotas und ein Embedding-Warmup aus. Stelle deshalb sicher, dass Datenbank und Provider-Konfiguration erreichbar sind.
Backend:
```powershell
cd math-tutor/backend
......@@ -55,16 +89,30 @@ cd math-tutor/backend
python -m uvicorn app.main:app --reload
```
Frontend (Vite):
Frontend:
```powershell
cd math-tutor/frontend
pnpm run dev
```
### Task Deep Links
Das Vite-Dev-Frontend läuft auf `http://localhost:5173`. API-Aufrufe gehen im Development über den Vite-Proxy an das Backend.
## Dev-Proxy
Das Frontend ruft APIs relativ über `/api/...` auf. Im Development leitet Vite diese Reqüsts an das Backend weiter.
Sie können einen Aufgaben-Chat direkt über URL-Abfrageparameter öffnen:
Optional in `math-tutor/frontend/.env`:
```env
VITE_API_BASE_URL="http://localhost:8000"
```
Ohne diese Variable wird standardmäßig `http://localhost:8000` verwendet.
## Task Deep Links
Ein Aufgaben-Chat kann direkt per URL geöffnet werden:
`/chat?orchestrator=task&file_id=<task_file_id>&task_id=<task_id>`
......@@ -74,160 +122,142 @@ Beispiel:
Hinweise:
- `file_id` muss mit der ID einer vorhandenen Aufgabendatei aus dem Aufgabenkatalog übereinstimmen.
- `file_id` muss im Aufgabenkatalog vorhanden sein.
- `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.
- Bei ungültigen Werten fällt das Frontend auf `/select-task` zurück.
- Der Deep Link sperrt die Auswahl nicht daürhaft; Benutzer können später weiter wechseln.
### Socratic Deep Links
## Socratic Deep Links
Sie können einen Sokratischen Chat direkt über URL-Abfrageparameter öffnen:
Ein sokratischer Chat kann direkt per URL geöffnet werden:
`/chat?orchestrator=socratic&topic_key=<topic_key>`
Example:
Beispiel:
`http://localhost:5173/chat?orchestrator=socratic&topic_key=klammerrechnung`
Hinweise:
- `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.
- `topic_key` muss im sokratischen Themenkatalog vorhanden sein.
- Die App verwendet normalisierte Themen-Schlüssel in der URL.
- Bei ungültigen Werten fällt das Frontend auf `/select-socratic` zurück.
- Der Deep Link sperrt die Themenauswahl nicht daürhaft.
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.
## Datenbank und Retrieval
```powershell
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
pnpm run dev -- --host 0.0.0.0
```
Stelle sicher, dass `POSTGRES_URL` und die benötigten Embedding-Provider-Variablen in `backend/.env` gesetzt sind.
### Frontend package manager policy (pnpm)
Beispiel:
- 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`.
```env
POSTGRES_URL=postgresql://user:pass@host:5432/db
EMBEDDING_PROVIDER=sentence-transformer
SENTENCE_TRANSFORMER_MODEL=jinaai/jina-embeddings-v5-text-small-retrieval
EMBEDDING_DIM=512
```
### Vite Proxy (Development)
Schema initialisieren:
Das Frontend unterstützt nun einen Dev-Proxy für API-Aufrufe:
```powershell
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli init-db
```
- Das Frontend sendet Anfragen an `/api/...` an Vite
- Vite leitet `/api` an das Backend-Ziel weiter
Material einbetten:
Optional in `math-tutor/frontend/.env`:
```env
VITE_PROXY_TARGET="http://<BACKEND_HOST>:8000"
```powershell
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli ingest --base sources/lecture_script --clear
```
## Docker Compose (Production-style)
Die Ingestion erwartet innerhalb von `sources/lecture_script` die aktüllen Unterordner:
Template files:
- `sections`
- `subsections`
- `subsubsections`
- `childs`
- `math-tutor/docker/docker-compose.yaml`
- `math-tutor/docker/nginx.conf`
- `math-tutor/backend/Dockerfile`
- `math-tutor/frontend/Dockerfile`
Run:
Retrieval über die CLI:
```powershell
cd math-tutor/docker
docker compose up --build -d
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli qüry --q "Was ist eine Teilmenge?" --k 8 --expand
```
In browser öffnen:
## Orchestrator- und Retrieval-Konfiguration
- `http://<HOST>:80`
Der Standard-Orchestrator wird über `ORCHESTRATOR` in `backend/.env` festgelegt. Verfügbare Werte sind:
Hinweise:
- `qa`
- `tutor`
- `task`
- `socratic`
- 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/...`).
Die registrierten Orchestratoren liegen unter `backend/app/deterministic_services/orchestrators/`.
## Database (pgvector) setup
Die zentralen Retrieval-Defaults liegen aktüll in:
Stelle sicher, dass `POSTGRES_URL` und die anderen Umgebungsvariablen in `backend/.env` enthalten sind:
- `backend/app/deterministic_services/orchestrators/orchestrator_base.py`
- `backend/app/deterministic_services/retrieval_store.py`
``` env
POSTGRES_URL=postgresql://user:pass@host:5432/db
OPENAI_BASE_URL=...
OPENAI_API_KEY=...
OPENAI_EMBED_MODEL=...
```
Die API für die Orchestrator-Konfiguration liegt in:
- `backend/app/api/orchestrator.py`
## Tests
Erstellen Sie die Postgres-Datenbank, bevor Sie „init“ ausführen.
Die Tests liegen unter `backend/test`.
Init DB schema:
Ein einfacher Gesamtlauf ist:
```powershell
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli init-db
python -m unittest discover test
```
Markdown docs einbetten (expects `markdown/sections`, `markdown/subsections`, `markdown/childs`):
Einzelne Tests können weiterhin direkt als Modul gestartet werden, zum Beispiel:
```powershell
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli ingest --base sources/lecture_script --clear
python -m test.generate_socratic_chats_test
```
Query via CLI:
## Sokratische Initial-Prompts generieren
```powershell
cd math-tutor/backend
.\.venv\Scripts\Activate.ps1
python -m scripts.retrieval_cli query --q "Was ist eine Teilmenge?" --k 8 --expand
python -m scripts.generate_socratic_chats --source-root sources/lecture_script --output sources/inital_socratic_prompt/initial_prompts.yaml
```
## Configuration
Verschiedene Orchestrators:
## Docker Compose Template
- Edit `math-tutor/backend/app/api/chat.py` and update `SYSTEM_PROMPT`.
Der aktülle Compose-Stack in `math-tutor/docker/docker-compose.yaml` ist ein Deployment-Template für einen externen Docker-Network-Namen `web`.
Retrieval settings:
Aktüll definiert die Datei:
- Frontend-Anfrageparameter befinden sich in `math-tutor/frontend/src/pages/App.tsx`:
- `k`
- `expand_links`
- `neighbor_expand`
- 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`).
- einen Service `backend-openai`
- einen Service `frontend-openai`
- keine direkten Port-Mappings nach außen
- ein externes Netzwerk `web`
## Testing
Derzeit gibt es mehrere Tests, um bestimmte Komponenten separat zu prüfen. Die genauen Aufrufe finden Sie in den Testdateien. Hier sind einige Beispielaufrufe.
Starten:
```powershell
python -m test.hint_test --chat-id draft_session_mlgmxxzc_avmjfb
python -m test.retrieval_store_test --query "Was ist eine Teilmenge?" --k 8 --expand
python -m test.retrieval_store_test --query "Was ist eine Teilmenge?" --k 3 --subsections 1-1-1
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
cd math-tutor/docker
docker compose up --build -d
```
## Generate Socratic Chats
Wichtige Hinweise:
```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
```
- Das Compose-Template erwartet `backend/.env-openai`.
- Das Frontend wird im Container von Nginx auf Port `3000` ausgeliefert.
- Nginx im Frontend leitet `/api` an `http://backend-openai:8000` weiter.
- Ohne eigene Port-Mappings oder einen vorgelagerten Reverse Proxy ist die App nicht automatisch unter `http://localhost:80` erreichbar.
- Die Datei `math-tutor/docker/nginx.conf` existiert nicht; die verwendete Nginx-Konfiguration liegt unter `math-tutor/frontend/nginx.conf`.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Dies ist die Gitlab-Instanz des Transferportals der Hochschule für Technik Stuttgart. Hier geht es zurück zum Portal