enhance rag retrieval + summary

2026-04-07 22:39:28 +02:00
parent 0cf318f0a7
commit aee6a9dfba
34 changed files with 2306 additions and 279 deletions
@@ -0,0 +1,68 @@
+# API Contract: Topics — Summary Persistence
+
+**Base path**: `/api/v1/topics`
+
+---
+
+## Existing endpoint (unchanged behaviour, extended response)
+
+### `POST /api/v1/topics/{id}/summary`
+
+Generates a new summary for the topic, **persists it**, and returns it.
+
+**Path param**: `id` — topic id (e.g. `intracranial-aneurysms`)
+
+**Response** `200 OK`:
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "summaryNumber": 3,
+  "topicId": "intracranial-aneurysms",
+  "topicName": "Intracranial Aneurysms",
+  "summary": "## Key Points\n...",
+  "sources": [
+    { "bookId": "uuid", "bookTitle": "Youmans & Winn", "page": 142 }
+  ],
+  "generatedAt": "2026-04-07T10:23:00Z"
+}
+```
+
+**Error responses**:
+- `404 Not Found` — topic id does not exist
+- `503 Service Unavailable` — no books ready (existing `NoKnowledgeSourceException`)
+
+---
+
+## New endpoints
+
+### `GET /api/v1/topics/{id}/summaries`
+
+Returns the list of saved summaries for a topic (no full text — list metadata only).
+
+**Path param**: `id` — topic id
+
+**Response** `200 OK`:
+```json
+[
+  { "id": "uuid-1", "summaryNumber": 1, "generatedAt": "2026-04-06T08:00:00Z" },
+  { "id": "uuid-2", "summaryNumber": 2, "generatedAt": "2026-04-06T09:15:00Z" }
+]
+```
+
+Ordered ascending by `summaryNumber`. Empty array if no summaries saved yet.
+
+**Error responses**:
+- `404 Not Found` — topic id does not exist
+
+---
+
+### `GET /api/v1/topics/{id}/summaries/{summaryId}`
+
+Fetches the full content of a specific saved summary.
+
+**Path params**: `id` — topic id, `summaryId` — summary UUID
+
+**Response** `200 OK`: same shape as `POST /summary` response above.
+
+**Error responses**:
+- `404 Not Found` — topic or summary not found