POTE/README.md

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

# 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 – This file
• STATUS.md – Current project status
• FREE_TESTING_QUICKSTART.md – Test for $0
• OFFLINE_DEMO.md – Works without internet!

Deployment:

• docs/07_deployment.md – Full deployment guide
• docs/08_proxmox_deployment.md – ⭐ Proxmox-specific guide
• Dockerfile + docker-compose.yml

Technical:

• docs/00_mvp.md – MVP roadmap
• docs/01_architecture.md – Architecture
• docs/02_data_model.md – Database schema
• docs/03_data_sources.md – Data sources
• docs/04_safety_ethics.md – Research-only guardrails
• docs/05_dev_setup.md – Dev conventions
• docs/06_free_testing_data.md – Testing strategies

PR Summaries:

• docs/PR1_SUMMARY.md – Scaffold + price loader
• docs/PR2_SUMMARY.md – Congressional trades
• 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 for the full roadmap.

---

License: MIT (for research/educational use only)
Disclaimer: Not investment advice. Use public data only. No claims about inside information.