143 lines
4.3 KiB
Markdown
143 lines
4.3 KiB
Markdown
# Quickstart: Neurosurgeon RAG Learning Platform
|
|
|
|
**Branch**: `001-neuro-rag-learning`
|
|
**Date**: 2026-03-31
|
|
|
|
This guide covers how to run the full stack locally and validate each user story manually
|
|
(per Principle V — POC Validation Gate).
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Version | Notes |
|
|
|------|---------|-------|
|
|
| Java | 21+ | Check: `java -version` |
|
|
| Maven | 3.9+ | Check: `mvn -version` |
|
|
| Node.js | 20+ | Check: `node -version` |
|
|
| Docker + Compose | any recent | PostgreSQL with pgvector is provided via Docker |
|
|
| PostgreSQL + pgvector | provided | See environment setup below |
|
|
|
|
---
|
|
|
|
## Environment Setup
|
|
|
|
1. **Start the database** (pgvector already provided — configure connection):
|
|
|
|
```properties
|
|
# backend/src/main/resources/application.properties
|
|
spring.datasource.url=jdbc:postgresql://localhost:5432/aiteacher
|
|
spring.datasource.username=aiteacher
|
|
spring.datasource.password=<your-password>
|
|
|
|
# Spring AI — vector store
|
|
spring.ai.vectorstore.pgvector.dimensions=1536
|
|
spring.ai.vectorstore.pgvector.distance-type=COSINE_DISTANCE
|
|
|
|
# Spring AI — LLM provider (example: OpenAI)
|
|
spring.ai.openai.api-key=${OPENAI_API_KEY}
|
|
spring.ai.openai.chat.options.model=gpt-4o
|
|
spring.ai.openai.embedding.options.model=text-embedding-3-small
|
|
|
|
# Shared password auth
|
|
spring.security.user.name=neurosurgeon
|
|
spring.security.user.password=${APP_PASSWORD}
|
|
```
|
|
|
|
2. **Set environment variables**:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY=sk-...
|
|
export APP_PASSWORD=changeme
|
|
```
|
|
|
|
---
|
|
|
|
## Running Locally
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd backend
|
|
mvn spring-boot:run
|
|
# API available at http://localhost:8080
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
# UI available at http://localhost:5173
|
|
```
|
|
|
|
---
|
|
|
|
## Smoke Tests (Principle V Validation)
|
|
|
|
Run these after the full stack is up to confirm each user story works end-to-end.
|
|
|
|
### Smoke Test 1 — Book Upload & Embedding (US1 / P1)
|
|
|
|
1. Open `http://localhost:5173` in a browser.
|
|
2. Navigate to the **Library** section.
|
|
3. Upload a PDF textbook (any medical PDF, 10+ pages with diagrams).
|
|
4. Observe status changes: `PENDING` → `PROCESSING` → `READY`.
|
|
5. **Pass criteria**: Book appears as `READY` within 10 minutes.
|
|
6. **Diagram check**: Ask a topic question in Smoke Test 2 that references a diagram
|
|
caption from the book — confirm it surfaces.
|
|
|
|
### Smoke Test 2 — Topic Summary (US2 / P2)
|
|
|
|
1. At least one book MUST be in `READY` state.
|
|
2. Navigate to the **Topics** section.
|
|
3. Select any topic from the list.
|
|
4. Click **Generate Summary**.
|
|
5. **Pass criteria**:
|
|
- Summary appears within 30 seconds.
|
|
- At least one source citation is shown with a book title and page number.
|
|
- The summary content is visibly related to the selected topic.
|
|
6. **No-source check**: Select a topic completely unrelated to your uploaded book.
|
|
Confirm the system responds with a clear "no relevant content found" message rather
|
|
than a hallucinated answer.
|
|
|
|
### Smoke Test 3 — Knowledge Chat (US3 / P3)
|
|
|
|
1. Navigate to the **Chat** section.
|
|
2. Start a new session (optionally tied to a topic).
|
|
3. Ask a specific clinical question answerable from the uploaded book.
|
|
4. **Pass criteria**:
|
|
- Response arrives within 30 seconds.
|
|
- Response cites a source book and page number.
|
|
5. Ask a follow-up question that references the previous answer
|
|
(e.g., "Can you expand on the grading scale you mentioned?").
|
|
6. **Pass criteria**: The response is coherent and contextually connected to the prior turn.
|
|
7. Ask something completely outside the books' content.
|
|
8. **Pass criteria**: The system explicitly states it cannot find relevant information
|
|
(not a hallucinated answer).
|
|
9. Use **Clear conversation** and verify the session resets.
|
|
|
|
---
|
|
|
|
## README Architecture Requirement (Principle IV)
|
|
|
|
The `README.md` at the repo root MUST contain at minimum this system-context diagram
|
|
(update as the architecture evolves):
|
|
|
|
```mermaid
|
|
graph TD
|
|
User["Neurosurgeon (Browser)"]
|
|
FE["Frontend\nVue.js 3 / Vite\n:5173"]
|
|
BE["Backend\nSpring Boot 4 / Spring AI\n:8080"]
|
|
DB["PostgreSQL + pgvector\n(provided)"]
|
|
LLM["LLM Provider\n(OpenAI / configurable)"]
|
|
|
|
User -->|HTTP| FE
|
|
FE -->|REST /api/v1/...| BE
|
|
BE -->|JDBC / pgvector| DB
|
|
BE -->|Embedding + Chat API| LLM
|
|
```
|
|
|
|
Copy this diagram into `README.md` to satisfy Principle IV before the PR is merged.
|