# Project notes for agents

## Relaunch the Streamlit server after changing ANY module other than app.py

The UI server runs on the **fixed port 8599** (started by `run.sh` or
`fundlab/server_watchdog.sh`, which keeps it alive every 5 min).

**Streamlit hot-reloads `app.py` on edit, but imported modules
(`metrics.py`, `data.py`, `portfolio.py`, `tax.py`, `fundlab/*`, ...)
stay cached in `sys.modules` for the process's whole lifetime.**
After editing any of those, the live server keeps running the OLD code
paired with the NEW `app.py` — a classic symptom is a cryptic TypeError
/ AttributeError on the page even though `tests/test_app.py` passes
(it spins up a fresh AppTest process).

After touching anything `app.py` imports, relaunch the server:

```bash
cd /mnt/Backup/prog/f
pkill -f 'streamlit run app\.py'; sleep 3
setsid nohup .venv/bin/streamlit run app.py --server.port 8599 \
  --server.headless true --browser.gatherUsageStats false \
  >> fundlab/streamlit.log 2>&1 < /dev/null & disown
# wait for health:
curl -s http://127.0.0.1:8599/_stcore/health   # -> ok
```

(Or just `pkill` it and let the watchdog relaunch within 5 min.)
Note: `setsid ... &` from a short-lived shell may die with the shell in
some harnesses — if the health check never answers, retry the relaunch
from a longer-lived command.

Verify on the LIVE server with the browser test (server must be running):

```bash
.venv/bin/python tests/test_e2e_browser.py
```

## Tests

- `.venv/bin/python tests/test_app.py` — AppTest suite (no server needed).
- `.venv/bin/python tests/test_e2e_browser.py` — Playwright against the
  live 8599 server.
- Both back up / restore `settings.json`; neither starts the server
  (e2e) or needs it (test_app).

## Conventions

- **Risk-free rate = BIL (SPDR 1-3 Month T-Bill) daily total return**
  from the data bundle — the single tool-wide convention for rf
  (`fundlab/decompose.rf_series()` is the reference). Statistics tab
  Sharpe/Sortino/alpha are in excess of it (`metrics.excess()`). Do not
  introduce fixed/constant rf rates elsewhere.
- Data root is `~/prog/fin/stocks`; symbols in the bundle are lowercase.