plan

2026-03-31 15:42:49 +02:00
parent 3507ce27e5
commit dc0bcab36e
10 changed files with 1246 additions and 0 deletions
--- a/specs/001-neuro-rag-learning/contracts/chat-api.md
+++ b/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.