0. Prereqs

macOS/Linux (similar on Windows with PowerShell)

Python 3.9+

Node.js 18+ and npm

Mistral API key

1. Clone & enter git clone <YOUR_REPO_URL> ww1-chatbot cd ww1-chatbot

2. Python env & deps python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt

3. Data paths & Mistral key

A. Ensure your corpus is present (text files):

ww1-chatbot/ backend/ data_cleaned/ # <- .txt files live here

B. Create .env in repo root:

cat > .env << 'EOF' MISTRAL_API_KEY=sk_your_key_here

absolute paths recommended

DATA_TXT_DIR=/Users//code/ww1-chatbot/backend/data_cleaned

optional; not required by the current API

DATA_JSON_DIR=/Users//code/ww1-chatbot/data

EOF

Replace paths with your actual absolute paths.

4. Run the backend (FastAPI)

Open a terminal in the repo root:

If a previous run left the port in use, kill it (optional)

lsof -n -i :8020

kill -9

Start API

PYTHONPATH=. uvicorn backend.api:app --reload --port 8020

Quick health check (new terminal) curl -s http://127.0.0.1:8020/health

Expected JSON should show "ok": true and txt_dir_exists: true.

Quick answer check (optional) curl -s http://127.0.0.1:8020/answer
-H "Content-Type: application/json"
-d '{"question":"What was life like in the trenches?","top_k":5,"persona":"French","audience":"Historian"}'

Persona options: British | French | German | American Audience options: Student | General | Historian

5. Frontend setup cd frontend npm install

Create frontend/.env.local:

cat > .env.local << 'EOF' VITE_API_BASE=http://127.0.0.1:8020 EOF

Run the UI:

npm run dev

Open the URL shown (typically http://localhost:8080 or the next free port).

6. What you should see

Persona & Audience dropdowns at the top.

Ask a question; the bot replies with quotes + [n] source tags.

Scroll below the message to see the retrieved passages.

7. Common fixes

Port already in use

backend port

lsof -n -i :8020 kill -9

frontend port

lsof -n -i :8080 kill -9

Health shows txt_dir_exists: false

Fix the path in .env (DATA_TXT_DIR must point to the folder that contains your .txt files).

Restart backend.

Frontend can’t reach API

Confirm backend is running on port 8020 and VITE_API_BASE matches.

Reload the browser after changes to .env.local.

8. Folder map (for reference) ww1-chatbot/ ├─ backend/ │ ├─ api.py # FastAPI app (answers + health) │ ├─ agents/ │ │ └─ retrieval_agent.py # BM25 retrieval │ └─ data_cleaned/ # your .txt corpus ├─ frontend/ │ ├─ src/ # React app │ ├─ .env.local # VITE_API_BASE=http://127.0.0.1:8020 │ └─ package.json ├─ .env # MISTRAL_API_KEY + DATA_TXT_DIR ├─ requirements.txt └─ README.md

9. Supervisor quickstart (TL;DR)

backend

cd ww1-chatbot python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt printf "MISTRAL_API_KEY=sk_xxx\nDATA_TXT_DIR=$(pwd)/backend/data_cleaned\n" > .env PYTHONPATH=. uvicorn backend.api:app --reload --port 8020

frontend (new terminal)

cd ww1-chatbot/frontend npm install printf "VITE_API_BASE=http://127.0.0.1:8020\n" > .env.local npm run dev