POTE/STATUS.md

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

# 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!)

# 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

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 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:

• 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

• Project structure (src/, tests/, docs)
• SQLAlchemy models (officials, securities, trades, prices)
• Alembic migrations
• yfinance price loader (idempotent, upsert)
• 15 tests passing
• Full linting setup

See: docs/PR1_SUMMARY.md

PR2: Congressional Trade Ingestion

• House Stock Watcher client (FREE API)
• Trade loader ETL (officials + trades)
• Test fixtures with realistic data
• 13 new tests (28 total passing)
• Smoke-test script for live ingestion
• Updated README + docs

See: 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 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 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 for testing strategies.