[verified] add BOT tourism source adapter

README.md

@@ -1,11 +1,11 @@
 # SET50 Alternative Data Platform
 
-Tourism-first vertical slice for a deterministic SET50 alternative-data research system.
+Tourism-first vertical slice for a deterministic SET50 alternative-data research system. The app can run against a clearly-labelled fixture or fetch a point-in-time Tourism Indicators vintage from the Bank of Thailand report backed by the Ministry of Tourism and Sports.
 
 Current scope:
 
 ```text
-fixture observation
+fixture or BOT source observation
   → Tourism Pulse surprise
   → versioned exposure score
   → ranked target weights
@@ -20,7 +20,7 @@ No external webhook receiver and no live MT5 execution are enabled.
 ```bash
 python -m venv .venv
 .venv/bin/pip install -r backend/requirements.txt
-PAPER_WRITE_TOKEN=local-paper-token PYTHONPATH=backend .venv/bin/python backend/run.py
+PAPER_WRITE_TOKEN=local-paper-token TOURISM_SOURCE=fixture PYTHONPATH=backend .venv/bin/python backend/run.py
 ```
 
 Health check:
@@ -45,6 +45,25 @@ The frontend reads the live API through Vite's `/api` proxy. Paper writes requir
 
 For HTTPS/non-local deployment, set `PAPER_COOKIE_SECURE=1`. The M0 session store is intentionally in-memory and single-process; use a shared session store before running multiple workers or replicas.
 
+## Run with the real BOT Tourism source
+
+Use the BOT-backed adapter when network access is available:
+
+```bash
+PAPER_WRITE_TOKEN=local-paper-token TOURISM_SOURCE=bot PYTHONPATH=backend .venv/bin/python backend/run.py
+```
+
+At startup the adapter performs a read-only GET/POST against the BOT Tourism Indicators report, parses the available monthly history, computes the latest year-over-year arrival observation against a trailing 12-point baseline, and stores the raw HTML plus normalized snapshot under `backend/data/` (ignored by git). The dashboard labels provisional BOT data as `provisional`, not `high`.
+
+Data-health and replay endpoints:
+
+```text
+GET /api/v1/data-health
+GET /api/v1/replay/tourism?vintage_id=<vintage_id>
+```
+
+Source: `https://app.bot.or.th/BTWS_STAT/statistics/ReportPage.aspx?reportID=875&language=eng`
+
 ## Tests and build
 
 ```bash
@@ -52,16 +71,18 @@ PYTHONPATH=backend .venv/bin/python -m unittest discover -s backend/tests -v
 cd frontend && npm run build
 ```
 
-## Current M0 boundary
+## Current M1 boundary
 
 - English UI and analysis vocabulary
 - Research mode and paper mode only
-- Tourism Pulse fixture adapter
+- Tourism Pulse fixture adapter and BOT Tourism Indicators adapter
 - Data lineage: source, publication time, retrieval time, vintage
+- Raw response hash and normalized snapshot persistence
+- Read-only data-health and vintage replay endpoints
 - Deterministic surprise × exposure × confidence score
 - Paper ledger endpoint
 - No LLM call yet; the deterministic result is the source of truth
 - No webhook receiver yet
 - No MT5 bridge yet
 
-The next implementation step is replacing the fixture with one replayable Tourism source adapter while preserving the same snapshot contract.
+The next implementation step is to validate multiple BOT vintages and add the next real Tourism metric before introducing LLM analysis.