Adrien
173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
# 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}`
|