From ea9479dc816a610ffd28513d0c1b808ddbdd71c4 Mon Sep 17 00:00:00 2001 From: Dotty Dotter Date: Fri, 10 Apr 2026 14:14:15 +0200 Subject: [PATCH] #62: API-Reference + Datenmodelle + Embeddings-Pipeline (mkdocstrings) --- docs/adr/index.md | 36 ++++++++++++++++ docs/archive/index.md | 26 +++++++++++ docs/index.md | 48 +++++++++++++++++++++ docs/reference/api.md | 83 ++++++++++++++++++++++++++++++++++++ docs/reference/embeddings.md | 46 ++++++++++++++++++++ docs/reference/models.md | 43 +++++++++++++++++++ mkdocs.yml | 14 ++++++ 7 files changed, 296 insertions(+) create mode 100644 docs/adr/index.md create mode 100644 docs/archive/index.md create mode 100644 docs/index.md create mode 100644 docs/reference/api.md create mode 100644 docs/reference/embeddings.md create mode 100644 docs/reference/models.md diff --git a/docs/adr/index.md b/docs/adr/index.md new file mode 100644 index 0000000..436ae3c --- /dev/null +++ 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. diff --git a/docs/archive/index.md b/docs/archive/index.md new file mode 100644 index 0000000..a696074 --- /dev/null +++ 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. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f9d0b00 --- /dev/null +++ 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//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. diff --git a/docs/reference/api.md b/docs/reference/api.md new file mode 100644 index 0000000..bab350f --- /dev/null +++ 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 | diff --git a/docs/reference/embeddings.md b/docs/reference/embeddings.md new file mode 100644 index 0000000..dd2eb82 --- /dev/null +++ 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 diff --git a/docs/reference/models.md b/docs/reference/models.md new file mode 100644 index 0000000..5a1644e --- /dev/null +++ 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 diff --git a/mkdocs.yml b/mkdocs.yml index 81d0021..3889c2d 100644 --- 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