buchwerk/API.md

buchwerk – Schnittstelle Backend ↔ Frontend

Backend: FastAPI auf Port 8020, liefert frontend/dist/ aus. Alle Pfade unter /api.

Adressen

Ein Thema hat einen Slug („Godot 4“ → godot-4) und Versionen v1, v2, … mit eigenem Lauf, Buch, Quellen und Leseposition. Die Version ist in der API immer Teil des Pfads; „neueste“ löst die Oberfläche selbst auf.

Seite: /<slug>, /<slug>/v2/lauf, /<slug>/v2/buch, /<slug>/v2/buch/3.4 (Abschnitt; 3 = Kapitel, vorwort), /<slug>/v2/lesen. Ohne v2 gilt die neueste Version.

Themen und Versionen

• GET /api/themen → [{slug, name, titel, hinweise, angelegt, status, laeuft, stufe, versionen: [{v, status, laeuft, stufe, angelegt, kosten_usd}]}] – status/laeuft/stufe gelten für die neueste Version; status: neu | laeuft | pausiert | fertig | fehler
• POST /api/themen {name, hinweise} → Thema wie oben (legt v1 an)
• GET /api/themen/{slug} → Thema wie oben
• DELETE /api/themen/{slug} – ganzes Thema
• POST /api/themen/{slug}/versionen → {"v": N} – nächste Version, gleiche Eingaben, ohne Start
• DELETE /api/themen/{slug}/v{N} – nur diese Version
• POST /api/themen/{slug}/v{N}/start – startet oder setzt fort (resümiert an der offenen Stufe)
• POST /api/themen/{slug}/v{N}/pause – bricht laufende Agenten ab; Neustart mit start
• POST /api/themen/{slug}/v{N}/reset – löscht alles in der Version außer dem Zustand „neu“
• GET|PUT /api/themen/{slug}/v{N}/position – Leseposition {abschnitt, lesemodus}

Stufen

recherche → gliederung → schreiben → pruefung → lektorat → konsistenz → montage. Das Lektorat glättet jedes geprüfte Kapitel Abschnitt für Abschnitt sprachlich (ohne Werkzeuge, prompts/lektorat.md); ein Abschnitt wird nur übernommen, wenn Bezeichner, Zahlen, Überschriften, Codeblöcke, Diagramme und Querverweise erhalten sind und der Umfang nicht über 20 % wächst. Marker: berichte/lektorat-NN.md. Alte Zustände ohne diese Stufe bekommen sie beim Laden nachgetragen.

Zustand eines Laufs

GET /api/themen/{slug}/v{N} →

{
  "slug": "godot-4", "name": "Godot 4", "version": 1, "titel": "Godot 4", "hinweise": "…",
  "status": "laeuft", "grund": "", "stufe": "schreiben", "angelegt": "2026-09-28T10:00:00Z",
  "deutung": {"titel": "Godot 4", "untertitel": "…", "deutung": "…", "buchtyp": "werkzeug|wissen", "zielgruppe": "…"},
  "stufen": [
    {"id": "recherche", "titel": "Thema deuten und Quellen beschaffen", "status": "fertig", "fertig": 1, "gesamt": 1,
     "kosten_usd": 1.2, "tokens": 250000, "gestartet": "2026-09-28T10:00:00Z", "beendet": "…"},
    {"id": "gliederung", "titel": "Gliederung", …},
    {"id": "schreiben", "titel": "Kapitel schreiben", "status": "laeuft", "fertig": 3, "gesamt": 18, …},
    {"id": "pruefung", "titel": "Kapitel prüfen", …},
    {"id": "konsistenz", "titel": "Doppelungen und Vorwort", …},
    {"id": "montage", "titel": "Buch zusammensetzen", …}
  ],
  "kosten_usd": 12.3, "tokens": 4100000,
  "agenten": [
    {"id": "kapitel-03", "stufe": "schreiben", "name": "Kapitel 3 schreiben", "status": "laeuft|fertig|fehler|abgebrochen",
     "kosten_usd": 0.9, "tokens": 180000, "werkzeuge": 41, "gestartet": "…", "beendet": "…", "bericht": "<Abschlussbericht, Markdown>"}
  ],
  "ereignisse": [{"zeit": "…", "agent": "kapitel-03", "art": "tool|text|start|ende|fehler", "text": "Write buch/03-dal.md"}]
}

stufen[].status: offen | laeuft | fertig | fehler. ereignisse sind die letzten 100.

Buch

GET /api/themen/{slug}/v{N}/buch →

{
  "titel": "Godot 4", "untertitel": "Architektur, Konzepte und Praxis der Engine", "status": "fertig",
  "vorwort": "<Markdown ohne H1>",
  "kapitel": [
    {"id": "03", "ord": 3, "titel": "GDScript", "teil": "Teil I – Grundlagen", "datei": "buch/03-gdscript.md",
     "status": "fehlt|geschrieben|geprueft|konsistent", "intro": "<Markdown vor dem ersten Abschnitt>",
     "abschnitte": [{"id": "03-1", "nr": "3.1", "titel": "Sprache und Syntax", "text": "<Markdown ohne die ##-Überschrift>", "woerter": 1400, "minuten": 8}],
     "woerter": 7000, "minuten": 39,
     "berichte": {"autor": "<Markdown>", "pruefer": "<Markdown>"}}
  ],
  "woerter": 130000, "minuten": 720,
  "gliederung": "<GLIEDERUNG.md>", "quellen": "<QUELLEN.md, Markdown>",
  "pdf": true
}

• GET /api/themen/{slug}/v{N}/buch.md – ganzes Buch als Markdown
• GET /api/themen/{slug}/v{N}/buch.pdf – PDF (404, solange nicht gebaut)

Solange ein Lauf läuft, enthält buch die bereits geschriebenen Kapitel (Status geschrieben, bis der Prüfer fertig ist).

Dateien im Speicher

storage/<Thema>/
  thema.json          {name, slug, titel, hinweise, angelegt}
  v1/, v2/, …         je Version:
    state.json        Zustand wie oben (ohne Buch)
    deutung.json      vom Recherche-Agenten
    position.json     Leseposition
    quellen/          QUELLEN.md + geklonte/geladene Quellen
    buch/             STIL.md, GLIEDERUNG.md, 00-vorwort.md, NN-*.md, README.md, buch.md, buch.pdf
    berichte/         <agent-id>.md (Abschlussberichte)
    arbeit/           Arbeitsdateien der Agenten
    log.jsonl         Ereignisse

Alte Ablagen (alles direkt unter storage/<Thema>/) werden beim Start nach v1/ verschoben, fehlende Slugs nachgetragen.