POTE (Public Officials Trading Explorer)

Research tool for tracking publicly disclosed stock trades by government officials (starting with U.S. Congress). Computes descriptive metrics and risk/ethics flags from lawfully available public data.

Not investment advice. Not for live trading. Public disclosures only; data may be delayed or incomplete. No claims about inside information.

Status: active. Homelab LXC deploy documented under docs/.

Quick start

git clone <repository-url>
cd pote   # or POTE
make install
source venv/bin/activate
make migrate
python scripts/ingest_from_fixtures.py   # offline sample
make test

With network:

python scripts/fetch_congressional_trades.py
python scripts/fetch_sample_prices.py

Deploy: bash scripts/proxmox_setup.sh or docker-compose up -d. Ops handoff: docs/HANDOFF-2026-05-27.md.

Useful commands

python scripts/analyze_official.py "Nancy Pelosi" --window 90
python scripts/calculate_all_returns.py
python scripts/monitor_market.py --scan
python scripts/send_daily_report.py --to your@email.com

Stack

Python 3.10+, SQLAlchemy, Alembic, pandas/numpy, httpx, yfinance. PostgreSQL or SQLite for local. pytest + ruff + mypy.

Data sources: House Stock Watcher, yfinance; QuiverQuant/FMP optional.

Docs

Doc	Purpose
docs/QUICKSTART.md	Using a deployed instance
docs/PROXMOX_QUICKSTART.md	Proxmox LXC
docs/AUTOMATION_QUICKSTART.md	Email reports
docs/01_architecture.md	Architecture
docs/02_data_model.md	Schema
docs/04_safety_ethics.md	Research guardrails
docs/07_deployment.md	Full deploy
docs/00_mvp.md	Roadmap

PR writeups live under docs/archive/ when moved.

License

MIT for research/educational use. Not investment advice.