buchwerk/API.md

buchwerk – Schnittstelle Backend ↔ Frontend

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

Themen

• GET /api/topics → [{name, titel, status, laeuft, stufe}]
  • status: neu | laeuft | pausiert | fertig | fehler
• POST /api/topics {name, hinweise} → Topic (name = Thema, z. B. „Godot 4“; hinweise optional, z. B. „für Entwickler, ab Version 4.6“)
• DELETE /api/topics/{name}
• POST /api/topics/{name}/start – startet oder setzt fort (resümiert an der Stufe, die noch offen ist)
• POST /api/topics/{name}/pause – bricht laufende Agenten ab; Neustart mit start
• POST /api/topics/{name}/reset – löscht alles außer thema.json

Zustand eines Laufs

GET /api/topics/{name}/state →

{
  "name": "Godot 4", "titel": "Godot 4", "hinweise": "…",
  "status": "laeuft", "grund": "", "stufe": "schreiben",
  "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": "Querverweise und Vorwort", …},
    {"id": "montage", "titel": "Buch zusammensetzen", …}
  ],
  "kosten_usd": 12.3, "tokens": 4100000,
  "agenten": [
    {"id": "schreiben-03", "stufe": "schreiben", "name": "Kapitel 3 schreiben", "status": "laeuft|fertig|fehler|abgebrochen",
     "kosten_usd": 0.9, "tokens": 180000, "werkzeuge": 41, "gestartet": "…", "beendet": "…", "bericht": "<Abschlussbericht des Agenten, Markdown>"}
  ],
  "ereignisse": [{"zeit": "…", "agent": "schreiben-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/topics/{name}/guide →

{
  "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/topics/{name}/guide.md – ganzes Buch als Markdown
• GET /api/topics/{name}/buch.pdf – PDF (404, solange nicht gebaut)

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

Dateien im Speicher

storage/<name>/
  thema.json          {name, titel, hinweise, angelegt}
  state.json          Zustand wie oben (ohne guide)
  deutung.json        vom Recherche-Agenten
  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)
  log.jsonl           Ereignisse

Versionen

Ein Thema kann mehrere Versionen haben (gleiche Eingaben, unabhängiger Lauf, eigenes Buch und eigene Leseposition). Ablage: storage/<Thema>/thema.json und storage/<Thema>/v<N>/…. Alte Ablagen werden beim Start nach v1/ verschoben.

• GET /api/topics liefert je Thema versionen: [{v, status, laeuft, stufe, angelegt, kosten_usd}]; die Felder status/laeuft/stufe gelten für die neueste Version.
• POST /api/topics/{name}/version → {"v": N} legt die nächste Version an (ohne Start).
• Alle Endpunkte unter /api/topics/{name}/… nehmen ?v=N; ohne Angabe gilt die neueste Version.
• DELETE /api/topics/{name}?v=N löscht nur diese Version, ohne v das ganze Thema.