cfaf38b0be
COMPLETE: Real-time unusual activity detection for congressional tickers
New Database Model:
- MarketAlert: Stores unusual market activity alerts
* Tracks volume spikes, price movements, volatility
* JSON details field for flexible data storage
* Severity scoring (1-10 scale)
* Indexed for efficient queries by ticker/timestamp
New Modules:
- src/pote/monitoring/market_monitor.py: Core monitoring engine
* get_congressional_watchlist(): Top 50 most-traded tickers
* check_ticker(): Analyze single stock for unusual activity
* scan_watchlist(): Batch analysis of multiple tickers
* Detection logic:
- Unusual volume (3x average)
- Price spikes/drops (>5%)
- High volatility (2x normal)
* save_alerts(): Persist to database
* get_recent_alerts(): Query historical alerts
- src/pote/monitoring/alert_manager.py: Alert formatting & filtering
* format_alert_text(): Human-readable output
* format_alert_html(): HTML email format
* filter_alerts(): By severity, ticker, type
* generate_summary_report(): Text/HTML reports
Scripts:
- scripts/monitor_market.py: CLI monitoring tool
* Continuous monitoring mode (--interval)
* One-time scan (--once)
* Custom ticker lists or auto-detect congressional watchlist
* Severity filtering (--min-severity)
* Report generation and saving
Migrations:
- alembic/versions/f44014715b40_add_market_alerts_table.py
Documentation:
- docs/11_live_market_monitoring.md: Complete explanation
* Why you can't track WHO is trading
* What IS possible (timing analysis)
* How hybrid monitoring works
* Data sources and APIs
Usage:
# Monitor congressional tickers (one-time scan)
python scripts/monitor_market.py --once
# Continuous monitoring (every 5 minutes)
python scripts/monitor_market.py --interval 300
# Monitor specific tickers
python scripts/monitor_market.py --tickers NVDA,MSFT,AAPL --once
Next Steps (Phase 2):
- Disclosure correlation engine
- Timing advantage calculator
- Suspicious trade flagging
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
✅ PR4 Complete: Phase 2 analytics - returns, benchmarks, performance metrics
45+ passing tests, 88%+ coverage
Quick start
🚀 Already deployed? See QUICKSTART.md for full usage guide!
📦 Deploying? See PROXMOX_QUICKSTART.md for Proxmox LXC deployment (recommended).
Local Development
# 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
python scripts/fetch_sample_prices.py
# Run tests
make test
# Lint & format
make lint format
Production Deployment
# Proxmox LXC (Recommended - 5 minutes)
bash scripts/proxmox_setup.sh
# Docker
docker-compose up -d
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 fileQUICKSTART.md– ⭐ How to use your deployed POTE instanceSTATUS.md– Current project statusFREE_TESTING_QUICKSTART.md– Test for $0OFFLINE_DEMO.md– Works without internet!
Deployment:
PROXMOX_QUICKSTART.md– ⭐ Proxmox quick deployment (5 min)docs/07_deployment.md– Full deployment guide (all platforms)docs/08_proxmox_deployment.md– Proxmox detailed guideDockerfile+docker-compose.yml– Docker setup
Technical:
docs/00_mvp.md– MVP roadmapdocs/01_architecture.md– Architecturedocs/02_data_model.md– Database schemadocs/03_data_sources.md– Data sourcesdocs/04_safety_ethics.md– Research-only guardrailsdocs/05_dev_setup.md– Dev conventionsdocs/06_free_testing_data.md– Testing strategies
PR Summaries:
docs/PR1_SUMMARY.md– Scaffold + price loaderdocs/PR2_SUMMARY.md– Congressional tradesdocs/PR3_SUMMARY.md– Enrichment + deploymentdocs/PR4_SUMMARY.md– ⭐ Analytics foundation (returns, benchmarks, metrics)
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
What You Can Do Now
Analyze Performance
# Analyze specific official
python scripts/analyze_official.py "Nancy Pelosi" --window 90
# System-wide analysis
python scripts/calculate_all_returns.py
Add More Data
# Manual entry
python scripts/add_custom_trades.py
# CSV import
python scripts/scrape_alternative_sources.py import trades.csv
Next Steps (Phase 3)
- Signals: "follow_research", "avoid_risk", "watch" with confidence scores
- Clustering: group officials by trading behavior patterns
- API: FastAPI backend for queries
- Dashboard: React/Streamlit visualization
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.