# POTE Project Status **Last Updated**: 2025-12-14 **Version**: Phase 1 Complete (PR1 + PR2) ## 🎉 What's Working Now ### Data Ingestion (FREE!) ✅ **Congressional Trades**: Live ingestion from House Stock Watcher ✅ **Stock Prices**: Daily OHLCV from yfinance ✅ **Officials**: Auto-populated from trade disclosures ✅ **Securities**: Auto-created, ready for enrichment ### Database ✅ **Schema**: Normalized (officials, securities, trades, prices, metrics stubs) ✅ **Migrations**: Alembic configured and applied ✅ **DB**: SQLite for dev, PostgreSQL-ready ### Code Quality ✅ **Tests**: 28 passing (86% coverage) ✅ **Linting**: ruff + mypy all green ✅ **Format**: black applied consistently ## 📊 Current Stats ```bash # Test Suite 28 tests passing in 1.2 seconds 86% code coverage # Code Structure 8 source files (376 statements) 5 test files (28 tests) 2 smoke-test scripts 9 documentation files # Dependencies All free/open-source: - httpx (HTTP client) - yfinance (stock prices) - SQLAlchemy + Alembic (DB) - pandas, numpy (analytics - ready) - pytest (testing) ``` ## 🚀 Quick Commands ### Fetch Live Data (FREE!) ```bash # Get last 30 days of congressional trades python scripts/fetch_congressional_trades.py --days 30 # Fetch prices for specific tickers python scripts/fetch_sample_prices.py # Or programmatically: from pote.db import SessionLocal from pote.ingestion.house_watcher import HouseWatcherClient from pote.ingestion.trade_loader import TradeLoader with HouseWatcherClient() as client: txns = client.fetch_recent_transactions(days=7) with SessionLocal() as session: loader = TradeLoader(session) counts = loader.ingest_transactions(txns) print(f"{counts['trades']} trades ingested") ``` ### Development ```bash make test # Run full test suite make lint # Lint with ruff + mypy make format # Format with black make migrate # Run Alembic migrations ``` ## 🏠 Deployment **Your Proxmox?** Perfect! See [`docs/08_proxmox_deployment.md`](docs/08_proxmox_deployment.md) for: - LXC container setup (lightweight, recommended) - VM with Docker (more isolated) - Complete setup script - Monitoring & maintenance - Cost: ~$10/mo (just power!) Other options in [`docs/07_deployment.md`](docs/07_deployment.md): - Local (SQLite) - $0 - VPS + Docker - $10-20/mo - Railway/Fly.io - $5-15/mo - AWS/GCP - $20-50/mo ## 📂 Project Structure ``` pote/ ├── README.md # Project overview ├── STATUS.md # This file ├── FREE_TESTING_QUICKSTART.md # How to test for $0 ├── pyproject.toml # Dependencies & config ├── Makefile # Dev commands ├── alembic.ini # Migrations config │ ├── docs/ │ ├── 00_mvp.md # MVP roadmap │ ├── 01_architecture.md # Module layout │ ├── 02_data_model.md # Database schema │ ├── 03_data_sources.md # API sources │ ├── 04_safety_ethics.md # Research-only guardrails │ ├── 05_dev_setup.md # Dev conventions │ ├── 06_free_testing_data.md # Free testing strategies │ ├── PR1_SUMMARY.md # PR1 details │ └── PR2_SUMMARY.md # PR2 details │ ├── src/pote/ │ ├── __init__.py │ ├── config.py # Settings management │ ├── db/ │ │ ├── __init__.py # Session factory │ │ └── models.py # SQLAlchemy models │ └── ingestion/ │ ├── __init__.py │ ├── house_watcher.py # Free congressional trade API │ ├── trade_loader.py # ETL for trades │ └── prices.py # yfinance price loader │ ├── tests/ │ ├── conftest.py # Pytest fixtures │ ├── fixtures/ │ │ └── sample_house_watcher.json │ ├── test_models.py # DB model tests │ ├── test_price_loader.py # Price ingestion tests │ ├── test_house_watcher.py # API client tests │ └── test_trade_loader.py # ETL tests │ └── scripts/ ├── fetch_congressional_trades.py # Live trade ingestion └── fetch_sample_prices.py # Live price fetch ``` ## 💰 Cost Breakdown | Component | Cost | Notes | |-----------|------|-------| | **House Stock Watcher** | $0 | Free community API, no rate limit | | **yfinance** | $0 | Free Yahoo Finance data | | **Database** | $0 | SQLite (local dev) | | **All Python libraries** | $0 | Open source | | **Testing** | $0 | No paid services needed | | **TOTAL** | **$0** | 100% free for research! | Optional paid upgrades (NOT needed): - QuiverQuant Pro: $30/mo (500 calls/mo free tier available) - Financial Modeling Prep: $15/mo (250 calls/day free tier available) - PostgreSQL hosting: $7+/mo (only if deploying) ## ✅ Completed PRs ### PR1: Project Scaffold + Price Loader - [x] Project structure (`src/`, `tests/`, docs) - [x] SQLAlchemy models (officials, securities, trades, prices) - [x] Alembic migrations - [x] yfinance price loader (idempotent, upsert) - [x] 15 tests passing - [x] Full linting setup **See**: [`docs/PR1_SUMMARY.md`](docs/PR1_SUMMARY.md) ### PR2: Congressional Trade Ingestion - [x] House Stock Watcher client (FREE API) - [x] Trade loader ETL (officials + trades) - [x] Test fixtures with realistic data - [x] 13 new tests (28 total passing) - [x] Smoke-test script for live ingestion - [x] Updated README + docs **See**: [`docs/PR2_SUMMARY.md`](docs/PR2_SUMMARY.md) ## 📋 Next Steps (Phase 2 - Analytics) ### PR3: Security Enrichment - [ ] Enrich securities table with yfinance (names, sectors, exchanges) - [ ] Add enrichment script + tests - [ ] Update securities on trade ingestion ### PR4: Abnormal Returns - [ ] Calculate returns over windows (1m, 3m, 6m) - [ ] Fetch benchmark returns (SPY, sector ETFs) - [ ] Compute abnormal returns - [ ] Store in `metrics_trade` table - [ ] Tests + validation ### PR5: Clustering & Signals - [ ] Build feature vectors per official - [ ] scikit-learn clustering (k-means, hierarchical) - [ ] Store cluster labels in `metrics_official` - [ ] Implement signals: "follow_research", "avoid_risk", "watch" - [ ] Each signal exposes metrics + caveats ### PR6: Dashboard (Optional) - [ ] FastAPI backend with read-only endpoints - [ ] Streamlit or minimal React frontend - [ ] Per-official timelines + charts - [ ] Sector heatmaps - [ ] Signals panel with disclaimers **See**: [`docs/00_mvp.md`](docs/00_mvp.md) for full roadmap ## 🔬 Research-Only Reminder **This tool is for private research and transparency analysis only.** - ❌ Not investment advice - ❌ Not a trading system - ❌ No claims about inside information - ✅ Public data only - ✅ Descriptive analytics - ✅ Research transparency See [`docs/04_safety_ethics.md`](docs/04_safety_ethics.md) for guardrails. ## 🤝 Contributing This is a personal research project, but if you want to use it: 1. Clone the repo 2. `make install && source venv/bin/activate` 3. `make migrate` 4. `python scripts/fetch_congressional_trades.py --days 7` 5. Start exploring! ## 📄 License MIT License (for research/educational use only) --- **Questions?** See [`docs/06_free_testing_data.md`](docs/06_free_testing_data.md) for testing strategies.