Trainer_LLM/PMO/WP-17-kickoff.md

WP-17 – Retriever & Composer (Kern ohne LLM)

Projektkontext

Wir entwickeln eine deterministische Planerstellung aus bestehenden plan_templates und exercises.
WP-15 hat die Collections, Indizes und CRUD-APIs für plan_templates und plans produktiv geliefert.
WP-02 stellt die exercises-Collection mit Capabilities und Qdrant-Anbindung bereit.

Technologie-Stack: Python 3.12, FastAPI, Qdrant

---

Ziele

Implementierung eines /plan/generate-Endpoints, der:

• Filter- und Vektor-Suche in Qdrant kombiniert
• Scoring nach Coverage, Diversity und Novelty durchführt
• Pläne deterministisch und ohne LLM generiert
• Zeitbudgets einhält und Wiederholungen (Novelty-Penalty) vermeidet

---

Deliverables

1. API: POST /plan/generate

   • Parameter: discipline, age_group, target_group, goals, time_budget_minutes, novelty_horizon (5), coverage_threshold (0.8), strict_mode
   • Rückgabe: Plan-JSON mit Exercises-Referenzen und Metadaten

2. Retriever

   • Filter-Layer (Payload)
   • Vector-Layer (Ranking)
   • Kombinierte Gewichtung

3. Composer

   • Sections aufbauen (aus Template oder Default)
   • Zeitbudget pro Section und Gesamt einhalten
   • Strict-Mode: nur gültige external_id

4. Scoring-Funktionen

   • Coverage (Capabilites-Abdeckung)
   • Diversity (Variabilität)
   • Novelty (Neuheit gegenüber Historie)

5. Tests

   • Unit-Tests (Scoring, Filter)
   • E2E: Template → Retriever → Composer → Persistenz

6. Dokumentation

   • OpenAPI-Beispiele, Parametrierung, Konfigurationsoptionen

---

Akzeptanzkriterien

• Identische Eingaben → identischer Plan (Determinismus)
• Keine doppelten Übungen im Plan
• Budget- und Coverage-Ziele in ≥95 % der Testfälle erreicht
• Novelty-Penalty wirkt wie konfiguriert

---

Risiken

• Konflikte zwischen Budget, Coverage, Novelty (Priorisierung erforderlich)
• Geringe Übungsvielfalt → eingeschränkte Ergebnisse
• Performance-Einbußen bei großen Collections

---

Technische Vorgaben

Voreinstellungen:

• novelty_horizon: 5
• coverage_threshold: 0.8
• Priorität bei Konflikt: 1. Budget, 2. Coverage, 3. Novelty

Benötigte Dateien:

• llm-api/plan_router.py (v0.13.4)
• llm-api/exercise_router.py (aus WP-02)
• scripts/bootstrap_qdrant_plans.py (v1.3.x)
• Schema-Definitionen für plan_templates und plans
• Beispiel-Datensätze (Golden-Cases)
• .env (ohne Secrets, mit API-URLs)

---

Prompt für das Entwicklerteam (direkt nutzbar)

Rolle: Entwicklerteam WP-17 – Retriever & Composer (Kern ohne LLM)
Aufgabe: Implementiere /plan/generate, der deterministisch aus plan_templates und exercises Pläne generiert.
Nutze Filter- und Vektor-Suche in Qdrant, Scoring-Funktionen (Coverage, Diversity, Novelty) und eine Composer-Logik, die Zeitbudgets einhält.
Parameter: discipline, age_group, target_group, goals, time_budget_minutes, novelty_horizon=5, coverage_threshold=0.8, strict_mode.
Anforderungen: Deterministische Ergebnisse, keine Duplikate, ≥95 % Zielerreichung bei Budget/Coverage, funktionierender Novelty-Penalty.
Rahmen: Python 3.12, FastAPI, Qdrant, vorhandene plan_templates/plans/exercises-Collections.
Liefere: Code, Unit- und E2E-Tests, OpenAPI-Doku mit Beispielen.
Dateien: siehe Liste oben.