#62: API-Reference + Datenmodelle + Embeddings-Pipeline (mkdocstrings)

2026-04-10 14:14:15 +02:00 · 2026-04-10 14:14:15 +02:00 · ea9479dc81
commit ea9479dc81
parent 59994fc5e3
7 changed files with 296 additions and 0 deletions
--- a/docs/adr/index.md
+++ b/docs/adr/index.md
@ -0,0 +1,36 @@
+# Architecture Decision Records (ADRs)
+
+ADRs dokumentieren signifikante Architektur-Entscheidungen mit Kontext, Optionen
+und Konsequenzen. Format inspiriert von [Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Workflow
+
+1. Neue Entscheidung steht an → Kopie von `template.md` mit nächster freier
+   Nummer (`NNNN-kebap-titel.md`).
+2. Status `proposed` → diskutiert in Issue/PR → bei Akzeptanz auf `accepted`.
+3. **Niemals editieren nach `accepted`.** Wenn eine Entscheidung sich ändert,
+   neuer ADR mit `Supersedes: NNNN-…` im Header und der alte ADR bekommt
+   `Superseded by: MMMM-…`.
+4. Status `deprecated` für Entscheidungen, die ohne Nachfolger auslaufen.
+
+## Index
+
+| ID | Titel | Status | Datum |
+|---|---|---|---|
+| [0001](0001-llm-citation-binding.md) | LLM-Citations server-seitig binden statt prompt-seitig | accepted | 2026-04-10 |
+| [0002](0002-adapter-architecture.md) | Adapter-Pattern mit ParlamentAdapter-Basisklasse + Registry | accepted | 2026-04-10 |
+| [0003](0003-citation-property-tests.md) | Sub-D Property-Verification: Zitate als Substring der zitierten PDF-Seite | accepted | 2026-04-10 |
+| [0004](0004-deployment-workflow.md) | Docker Compose Deploy mit DB-/Reports-Volume und SN-XML-Sonderpfad | accepted | 2026-04-10 |
+
+## Wann ADR, wann nicht
+
+| ADR-würdig | nicht ADR-würdig |
+|---|---|
+| Wahl zwischen mehreren plausiblen Architekturen mit Trade-offs | Bug-Fix |
+| Strukturelle Konsequenzen für mehrere Module | Refactoring innerhalb eines Moduls |
+| Reverse-Engineering-Findings die andere Adapter beeinflussen | Stiländerungen, Linting-Konventionen |
+| Neue externe Abhängigkeiten oder APIs | Dependency-Bumps ohne API-Änderung |
+| Workflow-Konventionen die mehrere Sessions überdauern müssen | Tagesgeschäft, Issue-Tracking |
+
+Faustregel: Wenn ein neuer Kollege (oder eine neue Session) die Entscheidung
+sonst rückgängig machen würde, gehört sie in einen ADR.
--- a/docs/archive/index.md
+++ b/docs/archive/index.md
@ -0,0 +1,26 @@
+# Archiv
+
+Hier liegen historische Doku-Snapshots, die **nicht mehr autoritativ** sind.
+Sie beschreiben jeweils einen Zustand zu einem bestimmten Zeitpunkt; vieles
+davon ist heute überholt.
+
+## Warum nicht löschen?
+
+- Sie sind als historische Quelle nützlich, wenn man verstehen will, wie
+  das Projekt zu einem früheren Zeitpunkt strukturiert war.
+- Manche Findings sind in die ADRs (`../adr/`) übernommen, andere bewusst
+  nicht — weil sie tagesaktueller Stand waren und nie ADR-würdig.
+
+## Inhalt
+
+| Datei | Stand | Beschreibung |
+|---|---|---|
+| `DOKUMENTATION-2026-03-24.md` | 2026-03-24 | Frühe Skript-basierte Architektur, vor dem Webapp-Migrate. Beschreibt `scripts/process_single.sh`-Workflow, der heute durch FastAPI-Backend ersetzt ist. |
+| `STATUS-2026-03-28.md` | 2026-03-28 | Tagesstand-Snapshot. Beschreibt v5-Prompt, Persistenz-Volume, Security-Headers — alle drei sind heute Standard. |
+| `README-2026-03-28.md` | 2026-03-28 | Erste Repo-README. Listet nur den NRW-Adapter (vor #2/#3/#4 und 13 weiteren BLs). Architektur-Diagramm ist veraltet. |
+
+## Wenn etwas davon noch wahr ist…
+
+…gehört es in einen ADR (`../adr/`) oder die generierte Reference (geplant
+für #62 Phase 2). Bitte **nicht** in einen neuen Status-Snapshot ziehen.
+Status-Snapshots sind die Drift-Falle, die wir hier vermeiden wollen.
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,48 @@
+# GWÖ-Antragsprüfer — Dokumentation
+
+Diese Dokumentation folgt dem [Diátaxis-Framework](https://diataxis.fr) und ist
+nach Funktion (nicht nach Themen) organisiert. Drift-immun durch klare Trennung:
+Reference wird aus dem Code generiert, ADRs sind immutable, Tutorials/How-to
+sind manuell gepflegt aber knapp.
+
+## Struktur
+
+```
+docs/
+├── README.md              ← du bist hier
+├── adr/                   Architecture Decision Records (immutable)
+│   ├── README.md          ADR-Index + Workflow
+│   ├── template.md        Template für neue ADRs
+│   └── NNNN-titel.md      Eine Datei pro Entscheidung
+└── archive/               Historische Snapshots, nicht autoritativ
+```
+
+Geplant für später (siehe Issue #62):
+
+```
+docs/
+├── reference/             ← mkdocs autodoc-Output (nicht eingecheckt)
+├── tutorials/             ← Erst-Schritt-Anleitungen
+├── how-to/                ← Aufgaben-orientiert, "wie deploye ich"
+└── explanation/           ← Hintergründe, Konzepte
+```
+
+## Nicht hier dokumentiert (bewusst)
+
+| Was | Wo |
+|---|---|
+| API-Reference (Endpoints, Models, Schemas) | Auto-generiert aus FastAPI/Pydantic, nicht in docs/ einchecken |
+| Code-Reference (Klassen, Funktionen) | mkdocstrings aus den Docstrings (geplant Phase 2) |
+| Aktueller Projekt-Stand / Issues | Gitea Issues — `repo.toppyr.de/tobias/gwoe-antragspruefer/issues` |
+| Onboarding für KI-assisted Coder | `CLAUDE.md` im Repo-Root |
+| Live-System-Status | `https://gwoe.toppyr.de/auswertungen` (dynamisches Dashboard) |
+| Memory der KI-Sessions | `~/.claude/projects/<projekt>/memory/` (privat) |
+
+## Gegen Drift
+
+- ADRs sind **immutable**: nie überschreiben, sondern bei Änderung mit einem
+  neuen ADR superseden, der den alten in seinem Header referenziert.
+- Reference wird aus dem Code generiert, **nie** von Hand gepflegt.
+- `docs/archive/` enthält historische Status-Files. Werden gelesen aber **nicht
+  aktualisiert**. Wenn etwas davon noch wahr ist, gehört es in einen ADR oder
+  in die generierte Reference, nicht in einen neuen Status-Snapshot.
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@ -0,0 +1,83 @@
+# API-Endpoints
+
+Automatisch generierte Referenz der FastAPI-Endpoints.
+
+## Analyse
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| POST | `/api/analyze-drucksache` | Keycloak (geplant) | Antrag aus Landtag-Portal analysieren |
+| POST | `/analyze` | Keycloak (geplant) | Freitext-Upload analysieren |
+| GET | `/status/{job_id}` | - | Job-Status abfragen |
+| GET | `/result/{job_id}` | - | Analyse-Ergebnis (HTML) |
+| GET | `/result/{job_id}/pdf` | - | Analyse-Ergebnis (PDF) |
+
+## Assessments
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/api/assessments` | - | Alle Bewertungen (optional `?bundesland=`) |
+| GET | `/api/assessment` | - | Einzelne Bewertung (`?drucksache=`) |
+| GET | `/api/assessment/pdf` | - | PDF-Download einer Bewertung |
+
+## Suche
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/api/search` | - | Interne DB-Suche (`?q=`, max 200 Zeichen) |
+| GET | `/api/search-landtag` | - | Live Landtags-Suche (`?q=&bundesland=`) |
+
+## Auswertungen
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/auswertungen` | - | Dashboard (HTML) |
+| GET | `/api/auswertungen/matrix` | - | Aggregations-Matrix (JSON, `?wahlperiode=`) |
+| GET | `/api/auswertungen/zeitreihe` | - | Score-Verlauf (JSON) |
+| GET | `/api/auswertungen/export.csv` | - | Long-Format-CSV aller Anträge |
+
+## Wahlprogramme
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/quellen` | - | Wahlprogramm-Übersicht (HTML) |
+| GET | `/api/programme` | - | Liste aller Programme (JSON) |
+| GET | `/api/programme/status` | - | Indexierungsstatus |
+| POST | `/api/programme/index` | Keycloak (geplant) | Programm(e) indexieren |
+| GET | `/api/wahlprogramm-cite` | - | PDF-Seite mit Zitat-Highlighting |
+
+## Zitat-Highlighting
+
+`GET /api/wahlprogramm-cite`
+
+Liefert ein vollständiges Wahlprogramm-PDF mit gelb markierter Zitat-Stelle.
+
+**Parameter:**
+
+| Param | Typ | Beschreibung |
+|---|---|---|
+| `pid` | string | PROGRAMME-Key (z.B. `gruene-grundsatz`) — alternativ `pdf` |
+| `pdf` | string | PDF-Dateiname (z.B. `gruene-grundsatzprogramm.pdf`) — Reverse-Lookup auf `pid` |
+| `seite` | int | Ziel-Seitennummer (1-indexed) |
+| `q` | string | Snippet-Text zum Highlighten (max 200 Zeichen) |
+| `ds` | string | Drucksache-Nr. (optional, für Auto-Re-Analyse bei nicht-verifizierbarem Zitat) |
+| `bl` | string | Bundesland-Code (optional, zusammen mit `ds` für Re-Analyse) |
+
+**Verhalten:**
+
+- Text gefunden → PDF mit gelber Highlight-Annotation, `X-Found-Page` Header
+- Text NICHT gefunden + `ds`+`bl` vorhanden → Assessment wird automatisch neu analysiert, HTML-Warte-Seite zurück
+- Unbekanntes Programm → 404
+- Ungültige Seite → 400
+
+## Bundesländer
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/api/bundeslaender` | - | Liste aller konfigurierten Bundesländer |
+
+## System
+
+| Methode | Pfad | Auth | Beschreibung |
+|---|---|---|---|
+| GET | `/health` | - | Health-Check |
--- a/docs/reference/embeddings.md
+++ b/docs/reference/embeddings.md
@ -0,0 +1,46 @@
+# Embeddings & Citation-Pipeline
+
+Semantische Suche in Wahlprogrammen, Zitat-Rekonstruktion und
+PDF-Highlighting.
+
+## Retrieval
+
+::: app.embeddings.find_relevant_chunks
+    options:
+      show_root_heading: true
+
+::: app.embeddings.get_relevant_quotes_for_antrag
+    options:
+      show_root_heading: true
+
+## Prompt-Formatierung
+
+::: app.embeddings.format_quotes_for_prompt
+    options:
+      show_root_heading: true
+
+## Citation Post-Processing (Issue #60)
+
+::: app.embeddings.reconstruct_zitate
+    options:
+      show_root_heading: true
+
+::: app.embeddings.find_chunk_for_text
+    options:
+      show_root_heading: true
+
+## PDF-Highlighting (Issue #47)
+
+::: app.embeddings.render_highlighted_page
+    options:
+      show_root_heading: true
+
+## Indexierung
+
+::: app.embeddings.index_programm
+    options:
+      show_root_heading: true
+
+::: app.embeddings.PROGRAMME
+    options:
+      show_root_heading: true
--- a/docs/reference/models.md
+++ b/docs/reference/models.md
@ -0,0 +1,43 @@
+# Datenmodelle
+
+## Assessment
+
+Das zentrale Bewertungs-Modell. Wird vom LLM als JSON erzeugt,
+durch `reconstruct_zitate` nachbearbeitet und per Pydantic validiert.
+
+::: app.models.Assessment
+    options:
+      show_root_heading: true
+      members_order: source
+
+## Untermodelle
+
+::: app.models.FraktionScores
+    options:
+      show_root_heading: true
+
+::: app.models.ProgrammScore
+    options:
+      show_root_heading: true
+
+::: app.models.Zitat
+    options:
+      show_root_heading: true
+
+::: app.models.MatrixEntry
+    options:
+      show_root_heading: true
+
+::: app.models.Verbesserung
+    options:
+      show_root_heading: true
+
+## Enums
+
+::: app.models.Empfehlung
+    options:
+      show_root_heading: true
+
+::: app.models.Verbesserungspotenzial
+    options:
+      show_root_heading: true
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -23,10 +23,24 @@ nav:
    - "0003 Citation-Property-Tests": adr/0003-citation-property-tests.md
    - "0004 Deployment-Workflow": adr/0004-deployment-workflow.md
  - Reference:
+    - API-Endpoints: reference/api.md
    - Adapter-Capabilities: reference/adapter-capabilities.md
+    - Datenmodelle: reference/models.md
+    - Embeddings & Citations: reference/embeddings.md
  - Archiv:
    - Übersicht: archive/index.md

+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            show_source: false
+            show_bases: true
+            heading_level: 3
+
 markdown_extensions:
  - tables
  - admonition