plan

specs/001-neuro-rag-learning/contracts/topics-api.md

@@ -0,0 +1,74 @@
+# Contract: Topics API
+
+**Base path**: `/api/v1/topics`
+**Auth**: HTTP Basic (shared credential) required on all endpoints.
+
+---
+
+## GET /api/v1/topics
+
+List all predefined neurosurgery topics.
+
+**Response 200 OK**:
+```json
+[
+  {
+    "id": "cerebral-aneurysm",
+    "name": "Cerebral Aneurysm Management",
+    "description": "Diagnosis, grading, and surgical/endovascular treatment of cerebral aneurysms.",
+    "category": "Vascular"
+  },
+  {
+    "id": "glioblastoma",
+    "name": "Glioblastoma (GBM)",
+    "description": "Pathophysiology, surgical resection strategies, and adjuvant therapy for GBM.",
+    "category": "Oncology"
+  }
+]
+```
+
+---
+
+## POST /api/v1/topics/{id}/summary
+
+Generate an AI summary for the selected topic by cross-referencing all READY books.
+
+**Path param**: `id` — topic slug (e.g., `cerebral-aneurysm`)
+
+**Response 200 OK**:
+```json
+{
+  "topicId": "cerebral-aneurysm",
+  "topicName": "Cerebral Aneurysm Management",
+  "summary": "Cerebral aneurysms are focal dilations of intracranial arteries...",
+  "sources": [
+    {
+      "bookTitle": "Principles of Neurosurgery",
+      "page": 312
+    },
+    {
+      "bookTitle": "Youmans and Winn Neurological Surgery",
+      "page": 1048
+    }
+  ],
+  "generatedAt": "2026-03-31T10:15:00Z"
+}
+```
+
+**Response 404 Not Found** (unknown topic):
+```json
+{ "error": "Topic not found." }
+```
+
+**Response 503 Service Unavailable** (no READY books):
+```json
+{ "error": "No books are available as knowledge sources. Please upload and process at least one book." }
+```
+
+---
+
+## Notes
+
+- Topics are read-only; they cannot be created or deleted via the API.
+- The topic list is loaded from `topics.json` at application startup.
+- Summary generation is synchronous for the POC (< 30 s per SC-002); no polling needed.