# 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.