ai-teacher/specs/002-image-aware-embedding/quickstart.md

Quickstart: Enhanced Embedding with Image Parsing and Metadata

Branch: 002-image-aware-embedding | Date: 2026-04-03

---

Prerequisites

• Docker Compose running (PostgreSQL + pgvector)
• OpenAI API key set in backend/src/main/resources/application.properties or as env var OPENAI_API_KEY
• Java 25 + Maven on PATH

---

New Configuration

Add to backend/src/main/resources/application.properties:

# Figure storage
app.figure-storage.base-path=./uploads
app.figure-storage.min-image-size-px=100

The uploads/figures/ directory is created automatically on first use. Add it to .gitignore.

---

Database Migration

Two new Flyway migrations run automatically on startup:

• V4__document_hierarchy.sql — adds chapter and section tables
• V5__figures_and_refs.sql — adds figure and chunk_figure_ref tables

No manual DB setup needed.

---

Re-embedding Existing Books

Books embedded by feature 001 (text-only) remain functional for text queries. To add image support, trigger a re-embed:

curl -X POST http://localhost:8080/api/v1/books/{bookId}/reembed \
  -u admin:password

The book transitions to PROCESSING, old chunks and figures are deleted, and the new image-aware pipeline runs. Status can be polled via GET /api/v1/books.

---

Verifying Image Extraction

1. Upload a PDF with diagrams: POST /api/v1/books/upload
2. Wait for status: "READY" via GET /api/v1/books
3. List figures: GET /api/v1/books/{id}/figures — should return at least one entry per image page
4. Ask a diagram-specific question in chat — response sources should include a type: "FIGURE" entry

---

Frontend: Rendering Inline Figures

The assistant message content field will contain figure references in the format [Fig. 12-4, p.184]. The frontend should:

1. Parse [Fig. X, p.N] patterns in assistant message text
2. Look up the matching entry in sources where type === "FIGURE"
3. Render the figure inline using the imageUrl field

---

Running Tests

cd backend
mvn test

Key new test classes:

• FigureExtractionServiceTest — unit tests for image extraction and classification
• NeurosurgeryRetrieverTest — unit tests for dual-search merge and deduplication
• BookEmbeddingServiceIntegrationTest — integration test: upload PDF with known figures, verify figures appear in GET /api/v1/books/{id}/figures