204cd0e75b
- PR1: Project scaffold, DB models, price loader - PR2: Congressional trade ingestion (House Stock Watcher) - PR3: Security enrichment + deployment infrastructure - 37 passing tests, 87%+ coverage - Docker + Proxmox deployment ready - Complete documentation - Works 100% offline with fixtures
114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# POTE – Public Officials Trading Explorer
|
||
|
||
**Research-only tool for tracking and analyzing public stock trades by government officials.**
|
||
|
||
⚠️ **Important**: This project is for personal research and transparency analysis only. It is **NOT** for investment advice or live trading.
|
||
|
||
## What is this?
|
||
|
||
POTE tracks stock trading activity of government officials (starting with U.S. Congress) using lawfully available public data sources. It computes research metrics, descriptive signals, and risk/ethics flags to help understand trading patterns.
|
||
|
||
## Key constraints
|
||
|
||
- **Public data only**: House Stock Watcher (free!), yfinance (free!), QuiverQuant/FMP (optional)
|
||
- **Research framing**: All outputs are descriptive analytics, not trading recommendations
|
||
- **No inside information claims**: We use public disclosures that may be delayed or incomplete
|
||
|
||
## Current Status
|
||
|
||
✅ **PR1 Complete**: Project scaffold, DB models, price loader
|
||
✅ **PR2 Complete**: Congressional trade ingestion (House Stock Watcher)
|
||
✅ **PR3 Complete**: Security enrichment + deployment infrastructure
|
||
**37 passing tests, 87%+ coverage**
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
# Install
|
||
git clone <your-repo>
|
||
cd pote
|
||
make install
|
||
source venv/bin/activate
|
||
|
||
# Run migrations
|
||
make migrate
|
||
|
||
# Ingest sample data (offline, for testing)
|
||
python scripts/ingest_from_fixtures.py
|
||
|
||
# Enrich securities with company info
|
||
python scripts/enrich_securities.py
|
||
|
||
# With internet:
|
||
python scripts/fetch_congressional_trades.py --days 30
|
||
python scripts/fetch_sample_prices.py
|
||
|
||
# Run tests
|
||
make test
|
||
|
||
# Lint & format
|
||
make lint format
|
||
```
|
||
|
||
## Tech stack
|
||
|
||
- **Language**: Python 3.10+
|
||
- **Database**: PostgreSQL or SQLite (dev)
|
||
- **Data**: House Stock Watcher (free!), yfinance (free!), QuiverQuant/FMP (optional)
|
||
- **Libraries**: SQLAlchemy, Alembic, pandas, numpy, httpx, yfinance, scikit-learn
|
||
- **Testing**: pytest (28 tests, 87%+ coverage)
|
||
|
||
## Documentation
|
||
|
||
**Getting Started**:
|
||
- [`README.md`](README.md) – This file
|
||
- [`STATUS.md`](STATUS.md) – Current project status
|
||
- [`FREE_TESTING_QUICKSTART.md`](FREE_TESTING_QUICKSTART.md) – Test for $0
|
||
- [`OFFLINE_DEMO.md`](OFFLINE_DEMO.md) – Works without internet!
|
||
|
||
**Deployment**:
|
||
- [`docs/07_deployment.md`](docs/07_deployment.md) – Full deployment guide
|
||
- [`docs/08_proxmox_deployment.md`](docs/08_proxmox_deployment.md) – ⭐ Proxmox-specific guide
|
||
- [`Dockerfile`](Dockerfile) + [`docker-compose.yml`](docker-compose.yml)
|
||
|
||
**Technical**:
|
||
- [`docs/00_mvp.md`](docs/00_mvp.md) – MVP roadmap
|
||
- [`docs/01_architecture.md`](docs/01_architecture.md) – Architecture
|
||
- [`docs/02_data_model.md`](docs/02_data_model.md) – Database schema
|
||
- [`docs/03_data_sources.md`](docs/03_data_sources.md) – Data sources
|
||
- [`docs/04_safety_ethics.md`](docs/04_safety_ethics.md) – Research-only guardrails
|
||
- [`docs/05_dev_setup.md`](docs/05_dev_setup.md) – Dev conventions
|
||
- [`docs/06_free_testing_data.md`](docs/06_free_testing_data.md) – Testing strategies
|
||
|
||
**PR Summaries**:
|
||
- [`docs/PR1_SUMMARY.md`](docs/PR1_SUMMARY.md) – Scaffold + price loader
|
||
- [`docs/PR2_SUMMARY.md`](docs/PR2_SUMMARY.md) – Congressional trades
|
||
- [`docs/PR3_SUMMARY.md`](docs/PR3_SUMMARY.md) – Enrichment + deployment
|
||
|
||
## What's Working Now
|
||
|
||
- ✅ SQLAlchemy models for officials, securities, trades, prices
|
||
- ✅ Alembic migrations
|
||
- ✅ Price loader with yfinance (idempotent, upsert)
|
||
- ✅ Congressional trade ingestion from House Stock Watcher (FREE!)
|
||
- ✅ Security enrichment (company names, sectors, industries)
|
||
- ✅ ETL to populate officials & trades tables
|
||
- ✅ Docker + deployment infrastructure
|
||
- ✅ 37 passing tests with 87%+ coverage
|
||
- ✅ Linting (ruff + mypy) all green
|
||
- ✅ Works 100% offline with fixtures
|
||
|
||
## Next Steps (Phase 2)
|
||
|
||
- Analytics: abnormal returns, benchmark comparisons
|
||
- Clustering: group officials by trading behavior
|
||
- Signals: "follow_research", "avoid_risk", "watch" with metrics
|
||
- Optional: FastAPI backend + dashboard
|
||
|
||
See [`docs/00_mvp.md`](docs/00_mvp.md) for the full roadmap.
|
||
|
||
---
|
||
|
||
**License**: MIT (for research/educational use only)
|
||
**Disclaimer**: Not investment advice. Use public data only. No claims about inside information.
|