# Tutor-MVP – Architektur- und Umsetzungsentwurf
**Status:** Entwurf zur Prüfung durch Professore und Argus
**Geltungsbereich:** Einzelquelle, textuelles Transkript oder vergleichbare Textquelle; Einsteiger-Lernmodul; K1 intern; keine produktiven Seiteneffekte.
## 1. Verbindliche Grenzen
- Tutor besitzt ausschließlich `/opt/struktur/tutor/` und schreibt nur nach `data/`, `exports/` und `runtime/`.
- `/opt/struktur/youtube-research/knowledge.db` und `/opt/struktur/content-extraction/data/content_extraction.db` sind **Quellen**, keine Tutor-Persistenz. Zugriff ausschließlich über Read-only-Adapter bzw. SQLite-URI `mode=ro`.
- Keine Änderungen an Quellen-Datenbanken, bestehenden Services, Cronjobs, systemd-Einheiten oder produktiven SMA-Daten.
- Keine automatische Veröffentlichung und keine externen Schreibzugriffe im MVP.
- Jede fachliche Aussage erhält Herkunft und Verifikationsstatus; Tutor-Erklärungen dürfen nicht als Quellenaussagen ausgegeben werden.
## 2. Zielarchitektur
```text
SourceRef (URI/Service + Identität)
|
v
ReadOnly Source Adapter
- YouTube Research adapter
- Content Extraction adapter
- plain-text adapter
|
v
Normalized SourceChunk + immutable source snapshot metadata
|
v
Claim Extractor -> Claim/Citation records -> Verification Gate
| |
| +--> verified / single_source / conflicting /
| unverified / tutor_inference
v
Didactic Planner -> LearningModule -> Lesson/Concept/Explanation/Question
|
+--> Markdown export / dialog context / later course & podcast outputs
Tutor-owned SQLite (data/tutor.db) stores metadata, claims, mappings, runs and outputs.
Original source bytes and databases remain outside Tutor and unchanged. `realm` is an explicit isolation boundary: the MVP permits only `building_tech` and `ai_automation`; `generation_run` and `learning_module` carry the realm and composite foreign keys prevent cross-realm topic/source/module links.
```
### Module und Verantwortungen
1. **Ingestion:** nimmt eine explizite Quellenreferenz an; liest, normalisiert und bildet stabile Chunk-IDs. Kein `POST`, kein Schreibadapter.
2. **Evidence & Verification:** extrahiert Claims, ordnet Chunks zu, führt Quellenhierarchie und Konfliktstatus; blockiert keine Ausgabe wegen Alter, sondern markiert fehlende Prüfung.
3. **Didactic:** ordnet verifizierte bzw. sichtbar unsichere Claims didaktisch; erzeugt Einsteigertexte, Beispiele, Fehler/Missverständnisse und Kontrollfragen.
4. **Export/Interaction:** erzeugt Markdown und liefert Antworten nur aus dem gespeicherten Modulkontext; jede Antwort verweist auf Citations und Unsicherheit.
## 3. Leseschnittstellen
Adaptervertrag (MVP):
```text
get_source(source_ref) -> SourceDescriptor
list_chunks(source_ref, cursor?) -> Iterable[SourceChunk]
get_chunk(source_ref, chunk_id, version) -> SourceChunk
health() -> ReadOnlyHealth
```
`SourceDescriptor` liefert mindestens `source_id`, `source_type`, `locator`, `provider`, `title` (falls vorhanden), `source_version`, `authority_rank`, `classification_status` und `realm` (nur bei `classified`). `ReadOnlyHealth` liefert Erreichbarkeit, Lesbarkeit, erkannte Quelle/Version und den geprüften Read-only-Modus.
Die Realm-Zuordnung ist eine Tutor-eigene Projektion, keine Behauptung über das Quellschema. Der Ingestion-Schritt setzt sie nur aus einer geprüften Topic-/Quellenklassifikation. Zulässige Zustände sind `classified` mit `realm=building_tech|ai_automation`, `needs_review` oder `unclassified` mit `realm=NULL`; die letzten beiden Zustände sind sichtbar zu kennzeichnen und dürfen nicht in einen Lernlauf gelangen.
Verbotene Methoden: `create`, `update`, `delete`, `sync`, `publish`, `write_back`.
Der Adapter darf nur explizit erlaubte Quellpfade/GET-Routen verwenden. Für das MVP ist `health()` der kanonische Tutor-interne Read-only-Probevertrag; ein externer HTTP-Health-Pfad darf erst nach Runtime-Nachweis durch @hermesvps konfiguriert werden. Health bedeutet lediglich Erreichbarkeit, Lesbarkeit, Identität und Read-only-Konfiguration; HTTP 404/400 auf einem unbestätigten `/health`-Pfad ist kein Ausfallnachweis.
Für SQLite wird eine separate Verbindung mit `file:...?...mode=ro` und `uri=True` verwendet. Die beiden bestätigten Quelldatenbanken haben derzeit Root-Eigentum; die von Hermes gemeldeten Dateimodi (`knowledge.db` 664, `content_extraction.db` 644) sind vor Integration als Berechtigungsrisiko zu bewerten. Tutor erhält keine Schreibberechtigung und keine direkten Schreibfunktionen.
## 4. Verarbeitung und Verifikation
Ein `GenerationRun` referenziert exakt eine Eingabequelle im MVP. Für jeden Claim wird gespeichert:
- `source_id`, `chunk_id`, `version` (Pflicht bei quellenbasierter Aussage)
- Claim-Text und Claim-Typ (`fact`, `definition`, `procedure`, `example`, `inference`)
- Quellenrang und unabhängige Bestätigungsanzahl
- Status: `verified_multi_source`, `verified_primary`, `single_source`, `conflicting`, `unverified`, `tutor_inference`, `didactic_simplification`
- Begründung und Review-Zeitpunkt
Ein Einzelquellen-MVP darf keine Aussage als „mehrfach bestätigt“ markieren. Bei Konflikten werden beide Positionen mit Quellenbezug ausgegeben; ungelöste Konflikte werden nicht stillschweigend vereinheitlicht. Didaktische Vereinfachungen müssen semantisch äquivalent bleiben oder als Vereinfachung gekennzeichnet werden.
Ein `quality_review` mit `needs_revision` setzt den Modulstatus zurück auf `quality_review` und erzeugt einen neuen, nachvollziehbaren Überarbeitungszyklus; `approved` ist erst nach erneutem bestandenem Review zulässig.
## 5. MVP-Ablauf und Abnahmekriterien
1. Quelle per Referenz auswählen; Adapter-Health und Read-only-Modus prüfen.
2. Chunks lesen und mit stabilen IDs persistieren; Quelldatenbank bleibt byte-/row-seitig unverändert.
3. Claims extrahieren, Citations speichern, Verifikationsstatus setzen.
4. Einsteiger-Lernmodul erzeugen: Ziel, Vorwissen, Begriffe, Grundzusammenhänge, Beispiele, Schrittfolge, Fehler/Missverständnisse, Zusammenfassung, Kontrollfragen, Rückfragehinweis.
5. Markdown exportieren; jede zentrale Aussage besitzt Citation oder sichtbare Unsicherheitsmarkierung.
6. Argus prüft Fachtreue, Quellenzuordnung und Verständlichkeit; erst danach Freigabestatus `approved`.
**Technische Gates:** keine Schreibmethode in Source-Adaptern; SQLite-Readonly-Verbindung; Tutor-Persistenz unter eigenem Pfad; Pflichtfelder der Quellen-ID vollständig; keine Ausgabe ohne Quellen-/Unsicherheitskennzeichnung; keine externen Delivery-Adapter.
## 6. Risiken und offene Entscheidungen
- Exakte GET-/Read-Modelle von YouTube Research und Content Extraction sowie deren passender Health-Endpunkt müssen vor Implementierung anhand OpenAPI/Routen und kontrollierter Read-only-Proben bestätigt werden.
- Das Quellschema kann sich ändern; Adapter benötigen Schema-/Versionserkennung und einen klaren Fehlerstatus statt stiller Fallbacks.
- „Unabhängige Quelle“ muss für Stufe 2 fachlich definiert werden; gleiche Transkript-Reposts zählen nicht automatisch unabhängig.
- MVP-Entscheidung: SQLite für Tutor-eigene Metadaten; keine Kopie der Originaldaten, nur Referenzen und gegebenenfalls normalisierte Chunks mit Herkunft.
- API-/UI-Ausbau, mehrere Quellen, Spezial-Tutor, Audio und Benutzerverwaltung bleiben nachgelagerte Stufen.