first implementation - image/drawing integration

2026-04-04 12:56:56 +02:00
parent fc5b22fba1
commit 5acfdd33c1
42 changed files with 2854 additions and 151 deletions
@@ -0,0 +1,172 @@
+# API Contracts: Enhanced Embedding with Image Parsing and Metadata
+
+**Branch**: `002-image-aware-embedding` | **Date**: 2026-04-03  
+**Base path**: `/api/v1`  
+**Auth**: HTTP Basic (existing)
+
+---
+
+## New / Changed Endpoints
+
+### 1. Re-embed a book (new)
+
+Triggers a full re-embedding of an already-processed book, replacing all existing chunks and
+figures with the new image-aware pipeline output. Safe to call on books previously embedded
+by feature 001.
+
+```
+POST /api/v1/books/{id}/reembed
+```
+
+**Path parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | UUID | Book ID |
+
+**Response** `202 Accepted`
+
+```json
+{ "bookId": "uuid", "status": "PROCESSING" }
+```
+
+**Error responses**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Book not found |
+| 409 | Book already in PROCESSING state |
+
+---
+
+### 2. Get figures for a book (new)
+
+Returns the list of extracted figures for a book, including their type, caption, and image URL.
+Used by the frontend to display a figure gallery or inline figures in chat responses.
+
+```
+GET /api/v1/books/{id}/figures
+```
+
+**Path parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | UUID | Book ID |
+
+**Response** `200 OK`
+
+```json
+[
+  {
+    "figureId": "youmans-7ed-fig-12-4",
+    "label": "Fig. 12-4",
+    "caption": "Coronal cross-section of the cavernous sinus showing cranial nerve relationships",
+    "figureType": "ANATOMICAL_DIAGRAM",
+    "page": 184,
+    "imageUrl": "/api/v1/figures/550e8400-e29b-41d4-a716-446655440000/youmans-7ed-fig-12-4.png",
+    "sectionId": "youmans-7ed-ch12-s2-3",
+    "sectionTitle": "Cavernous Sinus"
+  }
+]
+```
+
+**Error responses**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Book not found |
+
+---
+
+### 3. Serve figure image (new)
+
+Serves the extracted figure image file. Mounted as a static resource from the file store.
+
+```
+GET /api/v1/figures/{bookId}/{filename}
+```
+
+**Path parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `bookId` | UUID | Book ID |
+| `filename` | string | Image filename (e.g. `youmans-7ed-fig-12-4.png`) |
+
+**Response** `200 OK` — binary PNG  
+**Content-Type**: `image/png`
+
+**Error responses**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Image file not found |
+
+---
+
+### 4. Chat message response — extended source format (changed)
+
+The existing `POST /api/v1/chat/sessions/{id}/messages` endpoint is unchanged in its request
+format. The response `sources` field is extended to include figure references.
+
+**Existing request** (unchanged):
+
+```json
+{ "content": "Describe the anatomy of the cavernous sinus" }
+```
+
+**Response** `200 OK` — extended `sources`:
+
+```json
+{
+  "id": "uuid",
+  "role": "ASSISTANT",
+  "content": "The cavernous sinus is ... [Fig. 12-4, p.184] ...",
+  "sources": [
+    {
+      "type": "TEXT",
+      "bookTitle": "Youmans and Winn Neurological Surgery, 7th Ed.",
+      "page": 184,
+      "chunkText": "The cavernous sinus contains ..."
+    },
+    {
+      "type": "FIGURE",
+      "bookTitle": "Youmans and Winn Neurological Surgery, 7th Ed.",
+      "page": 184,
+      "figureId": "youmans-7ed-fig-12-4",
+      "label": "Fig. 12-4",
+      "caption": "Coronal cross-section of the cavernous sinus ...",
+      "figureType": "ANATOMICAL_DIAGRAM",
+      "imageUrl": "/api/v1/figures/550e8400-e29b-41d4-a716-446655440000/youmans-7ed-fig-12-4.png"
+    }
+  ],
+  "createdAt": "2026-04-03T12:00:00Z"
+}
+```
+
+**Changed fields in `sources` array**:
+
+| Field | Old | New |
+|-------|-----|-----|
+| `type` | absent | `"TEXT"` or `"FIGURE"` |
+| `figureId` | absent | figure ID string (FIGURE type only) |
+| `label` | absent | caption label (FIGURE type only) |
+| `caption` | absent | full caption (FIGURE type only) |
+| `figureType` | absent | enum name (FIGURE type only) |
+| `imageUrl` | absent | image URL (FIGURE type only) |
+
+---
+
+## Unchanged Endpoints
+
+All endpoints from feature 001 remain at their existing paths with no breaking changes:
+
+- `POST /api/v1/books/upload`
+- `GET /api/v1/books`
+- `DELETE /api/v1/books/{id}`
+- `GET /api/v1/topics`
+- `GET /api/v1/topics/{id}/summary`
+- `POST /api/v1/chat/sessions`
+- `GET /api/v1/chat/sessions/{id}/messages`
+- `DELETE /api/v1/chat/sessions/{id}`