plan

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

@@ -0,0 +1,103 @@
+# Contract: Books API
+
+**Base path**: `/api/v1/books`
+**Auth**: HTTP Basic (shared credential) required on all endpoints.
+
+---
+
+## POST /api/v1/books
+
+Upload a new book for embedding.
+
+**Request**: `multipart/form-data`
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| file | File | Yes | PDF only; max 100 MB |
+
+**Response 202 Accepted**:
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Principles of Neurosurgery",
+  "fileName": "principles-of-neurosurgery.pdf",
+  "status": "PENDING",
+  "uploadedAt": "2026-03-31T10:00:00Z"
+}
+```
+
+**Response 400 Bad Request** (unsupported format):
+```json
+{ "error": "Only PDF files are accepted." }
+```
+
+**Response 413 Payload Too Large**:
+```json
+{ "error": "File exceeds maximum size of 100 MB." }
+```
+
+---
+
+## GET /api/v1/books
+
+List all uploaded books with their current processing status.
+
+**Response 200 OK**:
+```json
+[
+  {
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "title": "Principles of Neurosurgery",
+    "fileName": "principles-of-neurosurgery.pdf",
+    "fileSizeBytes": 45234567,
+    "pageCount": 842,
+    "status": "READY",
+    "uploadedAt": "2026-03-31T10:00:00Z",
+    "processedAt": "2026-03-31T10:07:23Z"
+  }
+]
+```
+
+---
+
+## GET /api/v1/books/{id}
+
+Get status and metadata for a single book.
+
+**Path param**: `id` — UUID
+
+**Response 200 OK**: Same shape as a single item in the list above, plus optional `errorMessage` field when `status = FAILED`.
+
+**Response 404 Not Found**:
+```json
+{ "error": "Book not found." }
+```
+
+---
+
+## DELETE /api/v1/books/{id}
+
+Delete a book and all its embedding chunks.
+
+**Response 204 No Content**: Book deleted.
+
+**Response 404 Not Found**:
+```json
+{ "error": "Book not found." }
+```
+
+**Response 409 Conflict** (book currently processing):
+```json
+{ "error": "Cannot delete a book that is currently being processed." }
+```
+
+---
+
+## Status Lifecycle
+
+```
+PENDING   → returned immediately after upload
+PROCESSING → set when embedding pipeline starts
+READY      → set when all chunks are embedded
+FAILED     → set on any unrecoverable error; errorMessage populated
+```

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

@@ -0,0 +1,133 @@
+# Contract: Chat API
+
+**Base path**: `/api/v1/chat`
+**Auth**: HTTP Basic (shared credential) required on all endpoints.
+
+---
+
+## POST /api/v1/chat/sessions
+
+Create a new chat session, optionally tied to a topic.
+
+**Request body** (`application/json`):
+```json
+{
+  "topicId": "cerebral-aneurysm"
+}
+```
+`topicId` is optional. If omitted, the session is free-form (any neurosurgery question).
+
+**Response 201 Created**:
+```json
+{
+  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "topicId": "cerebral-aneurysm",
+  "createdAt": "2026-03-31T10:20:00Z"
+}
+```
+
+---
+
+## GET /api/v1/chat/sessions/{sessionId}/messages
+
+Retrieve the full message history for a session, ordered chronologically.
+
+**Path param**: `sessionId` — UUID
+
+**Response 200 OK**:
+```json
+[
+  {
+    "id": "msg-uuid-1",
+    "role": "USER",
+    "content": "What are the Hunt and Hess grading criteria?",
+    "createdAt": "2026-03-31T10:21:00Z"
+  },
+  {
+    "id": "msg-uuid-2",
+    "role": "ASSISTANT",
+    "content": "The Hunt and Hess scale grades subarachnoid haemorrhage severity...",
+    "sources": [
+      { "bookTitle": "Principles of Neurosurgery", "page": 318 }
+    ],
+    "createdAt": "2026-03-31T10:21:04Z"
+  }
+]
+```
+
+**Response 404 Not Found**:
+```json
+{ "error": "Session not found." }
+```
+
+---
+
+## POST /api/v1/chat/sessions/{sessionId}/messages
+
+Send a user message and receive an AI response grounded in uploaded books.
+
+**Path param**: `sessionId` — UUID
+
+**Request body** (`application/json`):
+```json
+{
+  "content": "What are the Hunt and Hess grading criteria?"
+}
+```
+
+**Response 200 OK**:
+```json
+{
+  "id": "msg-uuid-2",
+  "role": "ASSISTANT",
+  "content": "The Hunt and Hess scale grades subarachnoid haemorrhage severity on a scale of I–V...",
+  "sources": [
+    { "bookTitle": "Principles of Neurosurgery", "page": 318 }
+  ],
+  "createdAt": "2026-03-31T10:21:04Z"
+}
+```
+
+**When no source found** — response still 200 OK, but `sources` is empty and `content` explicitly states the limitation:
+```json
+{
+  "id": "msg-uuid-3",
+  "role": "ASSISTANT",
+  "content": "I could not find relevant information about this topic in the uploaded books.",
+  "sources": [],
+  "createdAt": "2026-03-31T10:22:00Z"
+}
+```
+
+**Response 404 Not Found**:
+```json
+{ "error": "Session not found." }
+```
+
+**Response 503 Service Unavailable** (no READY books):
+```json
+{ "error": "No books are available as knowledge sources." }
+```
+
+---
+
+## DELETE /api/v1/chat/sessions/{sessionId}
+
+Delete a session and all its messages (clear conversation history).
+
+**Response 204 No Content**: Session deleted.
+
+**Response 404 Not Found**:
+```json
+{ "error": "Session not found." }
+```
+
+---
+
+## Notes
+
+- Responses are synchronous for the POC; no streaming or SSE required at this stage.
+- The backend includes the full conversation history (all prior messages in the session)
+  in the LLM context window to maintain multi-turn coherence.
+- The AI is instructed via system prompt to answer **only** from retrieved book chunks
+  and to explicitly state when no relevant context was found.

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.