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 # Der Tutor
Dies ist ein Tutor-Bot der auf dem digitalen Lehrwerk von Anselm Knebusch beruht. Dies ist ein Tutor-Bot für ein digitales Lehrwerk. Die App unterstützt aktüll vier Orchestratoren:
Es gibt 4 Modi.
1. Ein Q&A-Modus in dem man Fragen zum den Inhalten des Skript stellen kann. 1. `qa` für Fragen zu den Inhalten des Materials
2. Ein offener Tutormodus in dem man eigene Fragen stellen kann und diese mit dem Bot besprechen kann 2. `tutor` für einen offeneren Tutor-Dialog
3. Ein geschlossener Task Modus in dem man Aufgaben aus dem Lehrwerk mit dem Tutorbot besprechn kann. 3. `task` für Aufgaben aus dem Lehrwerk
4. Ein Sokrates Modus in dem man ein sokratischen Dialog zu einem Abschnitt aus dem Lehrwerk führen kann. 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)] - Python für das Backend
- Ordner „sources“ mit Ihren Markdown-Dateien, strukturiert nach Abschnitten, Unterabschnitten und Unter-Unterabschnitten - Node.js 22.x oder neür für das Frontend
- OpenAI-Endpunkt - pnpm in der Version aus `frontend/package.json`
- Ollama-Instanz - 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 - `openai`
- `_subsection_map.yaml` als Zuordnung von Themen zu Indizes für Verweise auf Abschnitte, Unterabschnitte oder Unter-Unterabschnitte. - `gwdg`
- `mistral`
- `ollama`
Übersetzt mit DeepL.com (kostenlose Version) Unterstützte Embedding-Provider:
- `sentence-transformer`
- `openai`
- `gwdg`
## Setup ## 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 cd math-tutor/backend
python -m venv .venv python -m venv .venv
.\.venv\Scripts\Activate.ps1 .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt pip install -r requirements.txt
``` ```
Frontend (Vite): Frontend:
``` powershell ```powershell
cd math-tutor/frontend cd math-tutor/frontend
corepack enable corepack enable
pnpm install --frozen-lockfile 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 ```powershell
cd math-tutor/backend cd math-tutor/backend
...@@ -55,16 +89,30 @@ cd math-tutor/backend ...@@ -55,16 +89,30 @@ cd math-tutor/backend
python -m uvicorn app.main:app --reload python -m uvicorn app.main:app --reload
``` ```
Frontend (Vite): Frontend:
```powershell ```powershell
cd math-tutor/frontend cd math-tutor/frontend
pnpm run dev 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>` `/chat?orchestrator=task&file_id=<task_file_id>&task_id=<task_id>`
...@@ -74,160 +122,142 @@ Beispiel: ...@@ -74,160 +122,142 @@ Beispiel:
Hinweise: 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. - `task_id` muss in dieser Datei vorhanden sein.
- Ist der Link ungültig, weicht das Frontend auf `/select-task` aus. - Bei ungültigen Werten fällt das Frontend auf `/select-task` zurück.
- Die Aufgabe wird durch den Deep Link nicht gesperrt, sodass Benutzer anschließend weiterhin zwischen Aufgaben wechseln können. - 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>` `/chat?orchestrator=socratic&topic_key=<topic_key>`
Example: Beispiel:
`http://localhost:5173/chat?orchestrator=socratic&topic_key=klammerrechnung` `http://localhost:5173/chat?orchestrator=socratic&topic_key=klammerrechnung`
Hinweise: Hinweise:
- `topic_key` muss mit einem vorhandenen Sokratischen Thema aus dem Aufgabenkatalog übereinstimmen. - `topic_key` muss im sokratischen Themenkatalog vorhanden sein.
- Die Links verwenden normalisierte Themen-Schlüssel in der URL, und die App löst diese wieder in den Katalog-Schlüssel auf. - Die App verwendet normalisierte Themen-Schlüssel in der URL.
- Die Fallback-Seite `/select-socratic` zeigt nur das Themen-Dropdown-Menü und die Start-Schaltfläche an. - Bei ungültigen Werten fällt das Frontend auf `/select-socratic` zurück.
- Wenn der Link ungültig ist, weicht das Frontend auf `/select-socratic` aus. - Der Deep Link sperrt die Themenauswahl nicht daürhaft.
- Der Sokratische Dialog ist nicht durch einen Deep Link gesperrt, sodass Benutzer das Thema auch nachträglich noch wechseln können.
Um den Zugriff über das Netzwerk zu ermöglichen. ## Datenbank und Retrieval
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 Stelle sicher, dass `POSTGRES_URL` und die benötigten Embedding-Provider-Variablen in `backend/.env` gesetzt sind.
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
pnpm run dev -- --host 0.0.0.0
```
### Frontend package manager policy (pnpm) Beispiel:
- Erforderliche Versionen: ```env
- Node.js: 22.x oder neuer POSTGRES_URL=postgresql://user:pass@host:5432/db
- pnpm: über `math-tutor/frontend/package.json` (`packageManager`) festgelegt EMBEDDING_PROVIDER=sentence-transformer
- Richtlinie für die Lockdatei: SENTENCE_TRANSFORMER_MODEL=jinaai/jina-embeddings-v5-text-small-retrieval
- `pnpm-lock.yaml` festschreiben. EMBEDDING_DIM=512
- 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) 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 Material einbetten:
- Vite leitet `/api` an das Backend-Ziel weiter
Optional in `math-tutor/frontend/.env`: ```powershell
cd math-tutor/backend
```env .\.venv\Scripts\Activate.ps1
VITE_PROXY_TARGET="http://<BACKEND_HOST>:8000" 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` Retrieval über die CLI:
- `math-tutor/docker/nginx.conf`
- `math-tutor/backend/Dockerfile`
- `math-tutor/frontend/Dockerfile`
Run:
```powershell ```powershell
cd math-tutor/docker cd math-tutor/backend
docker compose up --build -d .\.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`). Die registrierten Orchestratoren liegen unter `backend/app/deterministic_services/orchestrators/`.
- Halten Sie die API-Aufrufe im Frontend in dieser Konfiguration relativ (`/api/...`).
## 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 Die API für die Orchestrator-Konfiguration liegt in:
POSTGRES_URL=postgresql://user:pass@host:5432/db
OPENAI_BASE_URL=... - `backend/app/api/orchestrator.py`
OPENAI_API_KEY=...
OPENAI_EMBED_MODEL=... ## 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 ```powershell
cd math-tutor/backend cd math-tutor/backend
.\.venv\Scripts\Activate.ps1 .\.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 ```powershell
cd math-tutor/backend cd math-tutor/backend
.\.venv\Scripts\Activate.ps1 .\.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 ```powershell
cd math-tutor/backend cd math-tutor/backend
.\.venv\Scripts\Activate.ps1 .\.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 ## Docker Compose Template
Verschiedene Orchestrators:
- 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`: - einen Service `backend-openai`
- `k` - einen Service `frontend-openai`
- `expand_links` - keine direkten Port-Mappings nach außen
- `neighbor_expand` - ein externes Netzwerk `web`
- 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 Starten:
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 ```powershell
python -m test.hint_test --chat-id draft_session_mlgmxxzc_avmjfb cd math-tutor/docker
docker compose up --build -d
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
``` ```
## Generate Socratic Chats Wichtige Hinweise:
```powershell - Das Compose-Template erwartet `backend/.env-openai`.
cd math-tutor/backend - Das Frontend wird im Container von Nginx auf Port `3000` ausgeliefert.
.\.venv\Scripts\Activate.ps1 - Nginx im Frontend leitet `/api` an `http://backend-openai:8000` weiter.
python -m scripts.generate_socratic_chats --source-root sources/lecture_script --output sources/inital_socratic_prompt/initial_prompts.yaml - 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