f/AGENTS.md

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:

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):

.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.