diff --git a/README.md b/README.md new file mode 100644 index 0000000..16df682 --- /dev/null +++ b/README.md @@ -0,0 +1,197 @@ +# GP 300 - Geopolitics Uncertainty Index + +[![PyPI version](https://badge.fury.io/py/gp300.svg)](https://badge.fury.io/py/gp300) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) + +A real-time geopolitical uncertainty index built on prediction market data from [Polymarket](https://polymarket.com). The GP 300 tracks the top 300 most actively traded geopolitics-related contracts to provide a single metric representing global geopolitical uncertainty. + +**Live Dashboard**: [https://gp300.y3z.ai](https://gp300.y3z.ai) + +## What is GP 300? + +The GP 300 Index aggregates prediction market data to measure geopolitical uncertainty in real-time. Similar to how the VIX measures market volatility or the S&P 500 tracks stock performance, the GP 300 applies proven index methodology to the emerging domain of prediction markets. + +**Key Insights**: +- **Higher index value** → More geopolitical uncertainty +- **Lower index value** → Markets perceive outcomes as more predictable + +**Coverage**: International relations, conflicts, sanctions, trade wars, territorial disputes, diplomatic negotiations, international organizations, and cross-border policy. Purely domestic political events are excluded. + +## Features + +- **Data-Driven**: Real-time computation from Polymarket's public APIs +- **Volume-Weighted**: Constituents ranked by 30-day trading volume with 5% concentration cap +- **Entropy-Based**: Measures uncertainty using normalized information entropy +- **Multi-Outcome Support**: Handles both binary contracts and mutually-exclusive multi-outcome events +- **Fully Automated**: Updates via scheduled Cloudflare Workers every 5 minutes, with additional daily and weekly jobs +- **Python CLI**: Query index data from the command line +- **Web Dashboard**: Live visualization with historical charts and constituent breakdown + +## Quick Start + +### Installation + +```bash +pip install gp300 +``` + +### Usage + +```bash +# Current index value +gp300 + +# Historical data (1D, 1W, 1M, 3M, YTD, 1Y, MAX) +gp300 history 1W +gp300 history MAX --limit 10 + +# List constituents +gp300 constituents +gp300 constituents --top 10 --sort entropy + +# JSON output (for piping to jq, scripts, etc.) +gp300 current --json +gp300 constituents --json +``` + +## CLI Commands + +| Command | Description | +|---------|-------------| +| `gp300` | Show current index value (default) | +| `gp300 current` | Same as bare `gp300` | +| `gp300 history [RANGE]` | Historical data. Options: `--limit N` | +| `gp300 constituents` | List constituents. Options: `--top N`, `--sort [weight\|entropy\|volume\|name]` | + +All commands support `--json` for raw JSON output and `-h` for help. + +## Methodology + +### Constituent Selection + +The index tracks the **top 300 geopolitics-related contracts** from Polymarket, ranked by 30-day trading volume. A buffer rule (240/360 threshold) prevents excessive turnover during reconstitution. + +### Index Calculation + +1. **Volume Weighting**: Contracts are weighted by their 30-day trading volume +2. **Concentration Cap**: No single contract can exceed 5% of the index +3. **Entropy Measurement**: For each contract, calculate normalized information entropy: + - Binary contracts: `H = -p*log₂(p) - (1-p)*log₂(1-p)`, normalized to [0,1] + - Multi-outcome events: Full Shannon entropy across all outcomes, normalized +4. **Index Value**: Weighted average of constituent entropies × divisor + +### Update Cycles + +- **5-minute updates**: Fetch latest prices and recompute index with frozen weights +- **Daily rebalance**: Recalculate weights based on current volume, apply 5% cap +- **Weekly reconstitution**: Re-rank eligible contracts, add/remove constituents using buffer rule + +## Architecture + +``` +Polymarket APIs (Gamma, CLOB) + ↓ + src/api.py (fetch events, markets, prices) + ↓ + src/engine.py (select constituents, compute weights, entropy, index) + ↓ + main.py (orchestrate update/rebalance/reconstitute cycles) + ↓ + db.py (store in SQLite) + ↓ + ├── public/index.html (web dashboard) + └── cli/ (Python CLI tool) +``` + +## Repository Structure + +``` +gp300/ +├── src/ # Core index engine +│ ├── api.py # Polymarket API client +│ ├── engine.py # Index computation logic +│ └── worker.py # Cloudflare Workers entry point +├── cli/ # CLI tool (published to PyPI) +│ ├── main.py # CLI commands (Click framework) +│ ├── api.py # CLI-specific API wrapper +│ └── formatting.py # Terminal output formatting (Rich library) +├── public/ # Static web dashboard +│ └── index.html # Live dashboard with charts +├── main.py # Orchestrator for index updates +├── backtest.py # Historical simulation mode +├── db.py # SQLite database interface +├── test_engine.py # Unit tests +├── schema.sql # Database schema +├── wrangler.toml # Cloudflare Workers config +└── gp300-plan.md # Technical specification (40KB) +``` + +## Development + +### Requirements + +- Python 3.10+ +- Dependencies: `httpx`, `click`, `rich` + +### Local Setup + +```bash +# Clone the repository +git clone https://github.com/y3zai/gp300.git +cd gp300 + +# Install the package and its CLI dependencies +pip install -e . + +# Run the CLI locally +python -m cli + +# Run tests +python test_engine.py +``` + +### Database + +The project uses SQLite for local development and Cloudflare D1 for production. The schema includes tables for: +- Index snapshots and historical data +- Constituent details and weights +- Rebalance/reconstitution events +- Update state tracking + +### Deployment + +Production deployment uses Cloudflare Workers with: +- Python Workers for serverless execution +- D1 database for persistent storage +- KV storage for caching +- Cron triggers for scheduled updates + +See `wrangler.toml` for configuration details. + +## Documentation + +- **[gp300-plan.md](./gp300-plan.md)**: Comprehensive technical specification covering API design, index methodology, weighting, and update cycles +- **[CLI_README.md](./CLI_README.md)**: CLI-specific documentation + +## Contributing + +Contributions are welcome! Please feel free to submit issues or pull requests. + +## License + +This repository does not currently include a LICENSE file. Until a license is added, all rights are reserved unless stated otherwise by the author. + +## Links + +- **Web Dashboard**: [https://gp300.y3z.ai](https://gp300.y3z.ai) +- **PyPI Package**: [https://pypi.org/project/gp300/](https://pypi.org/project/gp300/) +- **GitHub Repository**: [https://github.com/y3zai/gp300](https://github.com/y3zai/gp300) +- **Polymarket**: [https://polymarket.com](https://polymarket.com) + +## Author + +Yu Zheng + +--- + +*Inspired by traditional financial indices like the S&P 500 and VIX, applied to the emerging domain of prediction markets.*