DEMO.md

Boss demo — v2 (legacy UI + past-report mapping)

This guide is for non-developers testing the system in a browser.

Open http://localhost:8000 for the full legacy UI (index.html), now wired to the v2 backend. A simplified UI is at /v2.html.

What you are testing

• Surveyor field notes mapped onto full paragraphs from your firm's past reports
• Three AI levels: minimum, medium, maximum
• Section photos (up to 5 stored, 2 for AI vision)
• Source attribution — each section shows which past report, section, and paragraph it came from
• DOCX export with photos placed like past reports

Start the demo (Docker)

1. Install Docker Desktop.
2. Copy .env.example to .env in the project root.
3. Set OPENAI_API_KEY=sk-... in .env (required for medium/maximum AI and photo vision; minimum works without it for basic mapping).
4. From the project folder:

docker compose -f docker-compose.v2.yml up --build

5. Open http://localhost:8000 in Chrome or Edge.

First startup may take 1–2 minutes while the operator template and reference documents are ingested.

Start the demo (local Python)

pip install -r backend/requirements.txt
$env:OPENAI_API_KEY = "sk-your-key"
$env:MASTER_TEMPLATE_AUTO_INGEST = "true"
$env:REFERENCE_AUTO_INGEST_ENABLED = "true"
uvicorn backend.main:app --reload --port 8000

Open http://localhost:8000

Walkthrough for your boss

1. Sign in

• Tenant ID: default (recommended for first demo — uses pre-loaded template)
• Click Register once with any password (6+ characters), then Log in next time

New tenants are auto-provisioned from the default template but should upload their own past reports.

2. Setup — past reports

• Check the green Ready health line.
• If reference count is 0, upload 1–2 completed survey DOCX/PDF files (anonymised past reports).
• Click Refresh list to confirm filenames appear.

3. Notes

• Enter property type and tenure.
• Paste messy field notes, e.g.:

E2: concrete tile slipped south slope
D1: chimney mortar open at crown

• Choose Minimum, Medium, or Maximum AI.
• Click Start report draft (needed before photos).

4. Photos (optional)

• Expand a section (e.g. E2 Roof).
• Upload site photos.
• Click thumbnails to select up to 2 for AI (gold border).

5. Preview & export

• Generate preview — review section text and Source: lines (past report + paragraph).
• Download DOCX — open in Word; check photos and source footnotes.

Automated smoke test (engineers)

With the server running on port 8000:

python scripts/demo_v2_http.py

Exit code 0 = demo path healthy.

Troubleshooting

Issue	Fix
"No past reports ingested"	Upload reference DOCX/PDF in step 1
Preview fails with 400	Ensure at least one reference document is ingested
Empty / generic sections	Upload past reports with matching section headings (E2, D1, etc.)
Vision not working	Set OPENAI_API_KEY; select 2 photos for AI
Slow first run	FAISS ingest + embedding model download on cold start

What is not in this demo UI

• Proofread / Enhance modes map to medium/maximum interference (same v2 engine).
• Document manager / similarity return empty stubs.
• Notes file upload (extract-notes) is stubbed — paste notes into section fields.
• Per-section async jobs are simulated; generation runs one v2 full-report pass per batch.

Acceptance checklist (for sign-off)

• Health shows reference chunks > 0
• Notes about roof appear in roof section, not chimney
• Preview shows Past report "…", section …, paragraph …
• DOCX downloads and opens in Word
• Photos appear in relevant sections
• Sections with no notes keep past-report wording (for manual completion)