diff --git a/PMO/WP-17-kickoff.md b/PMO/WP-17-kickoff.md new file mode 100644 index 0000000..2c8398a --- /dev/null +++ b/PMO/WP-17-kickoff.md @@ -0,0 +1,90 @@ +# 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.