Add Polymarket scanner and dispute strategy infrastructure

.gitignore

@@ -22,3 +22,19 @@ logs/
 *.csv
 *.json
 !config/*.json
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Local partner-specific files (each partner creates their own)
+# Create a file named .gitignore.local with your personal ignores
+.gitignore.local
+local/
+
+# Personal notes/scratch (convention: prefix with your initials)
+# e.g., nate_notes.md, alex_scratch.py
+*_notes.md
+*_scratch.*
+*_local.*

AGENTS.md

@@ -0,0 +1,125 @@
+# PR3DICT Agent Instructions
+
+This document helps AI coding assistants understand and work with this codebase.
+
+---
+
+## Git Workflow (IMPORTANT - Follow This Process)
+
+**Repository Structure:**
+- **Your fork:** `https://github.com/Nate0-1999/pr3dict` (where you push)
+- **Upstream:** `https://github.com/aerichmo/PR3DICT` (partner's repo, PRs go here)
+
+**For Every Feature:**
+
+```
+1. CREATE BRANCH on your fork
+   git checkout main
+   git pull origin main
+   git checkout -b feature-name
+
+2. WORK ON FEATURE
+   - Make changes
+   - Test thoroughly
+   - Commit with clear message
+
+3. PUSH BRANCH to your fork
+   git push -u origin feature-name
+
+4. CREATE PR to your fork's main
+   → PR: Nate0-1999/pr3dict feature-name → Nate0-1999/pr3dict main
+   → User manually reviews and approves in GitHub
+   → WAIT for approval before proceeding
+
+5. AFTER APPROVAL, PR to upstream
+   → PR: Nate0-1999/pr3dict main → aerichmo/PR3DICT main
+   → Partner reviews and merges
+```
+
+**Never push directly to main. Always use branches and PRs.**
+
+---
+
+## Project Overview
+
+PR3DICT is a multi-strategy prediction market trading system. Current focus: **Dispute Prediction** on Polymarket.
+
+**Important Principles:**
+1. This is a multi-strategy repo - only modify dispute strategy related code
+2. Arbitrage strategy and trading engine are separate - don't touch them
+3. Only build features that have been discussed and verified
+4. All credentials must be gitignored
+
+## Architecture
+
+```
+src/
+├── data/           # Market data ingestion (DISPUTE FOCUS)
+│   ├── scanner.py  # Fetches markets from Polymarket Gamma API
+│   └── database.py # SQLite storage for markets & analyses
+├── strategies/     # Trading strategies (arbitrage is separate)
+├── platforms/      # API wrappers (Polymarket, Kalshi)
+├── engine/         # Core trading engine (not dispute-related)
+└── risk/           # Position sizing (not dispute-related)
+```
+
+## What's Been Built & Verified (Dispute Strategy)
+
+### Market Scanner (`src/data/scanner.py`)
+- Polls Polymarket Gamma API for markets in target liquidity range
+- Stores markets in SQLite for tracking
+- **Tested and working** - no auth needed for read-only access
+- Run: `python -m src.data.scanner --show-unanalyzed`
+
+### Database (`src/data/database.py`)
+- SQLite schema for `markets` and `analyses` tables
+- Tracks which markets have been analyzed
+- **Tested and working**
+
+### Strategy Documentation
+- `docs/DISPUTE_PREDICTION_STRATEGY.md` - Strategy overview
+- `docs/APPENDIX_KELLY_CRITERION.md` - Position sizing theory
+- `docs/WORKTREE_COLLAB_PROTOCOL.md` - Parallel branch/worktree operating rules
+
+## What's NOT Built Yet (Dispute Strategy)
+- LLM analysis pipeline (Tier 1 screening, Tier 2 deep analysis)
+- Dispute probability scoring
+- Trade execution for dispute strategy
+- RAG/Vector database for learning
+
+## Setup & Commands
+
+```bash
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run market scanner
+python -m src.data.scanner --show-unanalyzed
+
+# Query database
+sqlite3 data/markets.db "SELECT question, liquidity FROM markets ORDER BY liquidity DESC LIMIT 10;"
+```
+
+## Polymarket API Notes
+
+- **Gamma API** (read-only, no auth): `https://gamma-api.polymarket.com`
+- Requires `User-Agent` header or returns 403
+- Key fields: `question`, `description`, `resolutionSource`, `umaResolutionStatus`, `liquidityNum`
+
+## Credentials
+
+All credentials are gitignored. To set up:
+```bash
+cp config/example.env config/.env
+# Edit with your credentials
+```
+
+## Development Guidelines
+
+- **Don't over-build** - only implement features that have been discussed
+- **Test before committing** - verify new code works
+- **Update this doc** - after adding verified features

README.md

@@ -1,30 +1,69 @@
 # PR3DICT
 
-**Automated Prediction Market Trading System**
+**Multi-Strategy Prediction Market Trading System**
 
 ---
 
-## Executive Summary
+## Quick Start
 
-PR3DICT applies the battle-tested ST0CK methodology to prediction markets. It leverages the unified trading engine architecture, systematic risk management, and multi-platform API integration to exploit inefficiencies in this rapidly growing $200B+ industry.
+```bash
+# 1. Clone the repo
+git clone https://github.com/aerichmo/PR3DICT.git
+cd PR3DICT
 
-### Target Platforms
-- **Kalshi** — CFTC-regulated, REST/WebSocket/FIX APIs, Market Maker Program
-- **Polymarket** — Blockchain-native (Polygon/USDC), high liquidity on political/crypto events
+# 2. Create virtual environment
+python3 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
 
-### Core Strategy Edges
-1. **Arbitrage** — Binary complement, cross-platform, latency
-2. **Market Making** — Bid-ask spread capture, inventory management
-3. **Behavioral** — Longshot bias exploitation, overreaction reversion
-4. **Informational** — AI-driven probability forecasting
+# 3. Install dependencies
+pip install -r requirements.txt
 
-### Architecture (from ST0CK)
-| Component | Application |
-|-----------|-------------|
-| Unified Engine | Strategy pattern for parallel signal testing |
-| Redis Cache | Multi-TTL for orderbooks, probability trends, metadata |
-| Risk Management | Kelly Criterion + Portfolio Heat + Daily Loss Limits |
-| API Layer | Unified wrappers for cross-platform operations |
+# 4. Configure credentials (for trading - not needed for scanning)
+cp config/example.env config/.env
+# Edit .env with your API keys
+```
+
+---
+
+## Strategies
+
+| Strategy | Platform | Status |
+|----------|----------|--------|
+| **Arbitrage** | Kalshi, Polymarket | 🔵 Implemented |
+| **Dispute Prediction** | Polymarket | 🔨 In Development |
+
+### Arbitrage Strategy
+Exploits price inefficiencies:
+- Binary complement (YES + NO < $1.00)
+- Cross-platform differentials
+
+### Dispute Prediction Strategy (In Development)
+Exploits Polymarket resolution mechanism:
+- Identify markets likely to be disputed
+- Position before resolution chaos
+- See `docs/DISPUTE_PREDICTION_STRATEGY.md`
+
+---
+
+## Dispute Strategy: Current Progress
+
+```bash
+# Scan Polymarket for markets (no API key needed)
+python -m src.data.scanner --show-unanalyzed
+
+# View stored markets
+sqlite3 data/markets.db "SELECT question, liquidity FROM markets ORDER BY liquidity DESC LIMIT 10;"
+```
+
+**What's working:**
+- [x] Market scanner (Polymarket Gamma API)
+- [x] SQLite database for tracking markets
+- [x] Strategy documentation
+
+**What's next:**
+- [ ] LLM analysis pipeline
+- [ ] Dispute probability scoring
+- [ ] Trade execution
 
 ---
 
@@ -33,39 +72,41 @@ PR3DICT applies the battle-tested ST0CK methodology to prediction markets. It le
 ```
 PR3DICT/
 ├── src/
+│   ├── data/            # Market scanner & database
+│   ├── strategies/      # Trading strategies
+│   ├── platforms/       # Kalshi, Polymarket APIs
 │   ├── engine/          # Core trading engine
-│   ├── strategies/      # Arbitrage, market-making, behavioral
-│   ├── platforms/       # Kalshi, Polymarket API wrappers
-│   ├── data/            # Market data ingestion & caching
-│   └── risk/            # Position sizing, kill-switches
-├── config/              # Platform credentials, strategy params
-├── tests/               # Unit + integration tests
+│   └── risk/            # Position sizing
+├── data/                # SQLite database (gitignored)
+├── config/              # Environment config
 └── docs/                # Strategy documentation
 ```
 
 ---
 
-## Quick Start
+## Documentation
 
-```bash
-# Clone and install
-git clone <repo-url>
-cd PR3DICT
-pip install -r requirements.txt
+| Document | Description |
+|----------|-------------|
+| `docs/DISPUTE_PREDICTION_STRATEGY.md` | Dispute strategy overview |
+| `docs/APPENDIX_KELLY_CRITERION.md` | Position sizing theory |
+| `AGENTS.md` | AI assistant instructions |
 
-# Configure credentials
-cp config/example.env config/.env
-# Edit .env with Kalshi/Polymarket API keys
+---
 
-# Run (paper mode)
-python -m src.engine.main --mode paper
-```
+## Collaboration
 
----
+Multi-contributor repo. Each partner can:
+- Create `.gitignore.local` for personal ignores
+- Use `local/` directory for scratch files
+- Prefix personal files with initials (e.g., `nate_notes.md`)
 
-## Status
+### Security: Credentials Are Local Only
 
-🚧 **Phase 1: Foundation** — Building core engine and platform integrations.
+**Never commit credentials.** These are gitignored:
+- `config/.env` — API keys, wallet private keys
+- `*.env` — All environment files
+- `data/*.db` — Local database
 
 ---
 

docs/APPENDIX_KELLY_CRITERION.md

@@ -0,0 +1,85 @@
+# Appendix: Kelly Criterion
+
+**Position Sizing From First Principles**
+
+---
+
+## The Problem Kelly Was Solving
+
+In 1956, John Kelly was a physicist at Bell Labs working on information theory. He was interested in a practical question:
+
+> **If you have an edge in a repeated bet, how much should you wager each time to maximize long-term wealth?**
+
+The naive answer is "bet everything" — if you have an edge, more is better. But this leads to ruin: one loss and you're wiped out.
+
+The opposite extreme — betting a tiny fixed amount — is safe but leaves money on the table.
+
+Kelly wanted the optimal middle ground: **the bet size that maximizes the expected growth rate of your bankroll over many repeated bets.**
+
+---
+
+## The Insight
+
+Kelly realized this was an information theory problem. He framed it as: you have a noisy channel (your edge) transmitting information (the correct bet). How do you maximize the information rate?
+
+His key insight: **you should bet a fraction of your bankroll proportional to your edge.**
+
+---
+
+## The Formula
+
+For a simple bet with probability `p` of winning and odds `b` (you get back `b` times your bet if you win):
+
+```
+f* = (bp - q) / b
+
+where:
+  f* = fraction of bankroll to bet
+  p  = probability of winning
+  q  = probability of losing (1 - p)
+  b  = decimal odds - 1 (what you win per dollar risked)
+```
+
+**Example:**
+- You have 60% chance to win (p = 0.6)
+- Odds are even money (b = 1, you win $1 for every $1 risked)
+
+```
+f* = (1 × 0.6 - 0.4) / 1 = 0.2
+```
+
+You should bet 20% of your bankroll.
+
+---
+
+## Why It Works
+
+Kelly sizing has a special property: it maximizes the **geometric mean** of returns (equivalently, the expected log of wealth). This means:
+
+1. **You never go broke** — You're always betting a fraction, never everything
+2. **You grow faster than any other strategy** — In the long run, Kelly beats all other fixed-fraction approaches
+3. **Bet size scales with edge** — Bigger edge = bigger bet, no edge = no bet
+
+---
+
+## Why We Use Fractional Kelly
+
+Full Kelly is aggressive. In practice, we use a fraction (like 25%) because:
+- Our probability estimates have uncertainty
+- Drawdowns with full Kelly can be 50%+ (psychologically brutal)
+- Model errors compound; fractional Kelly provides a buffer
+
+For dispute trading specifically, we also discount for:
+- Confidence in our dispute prediction
+- Probability of INVALID resolution (both sides lose)
+
+---
+
+## Further Reading
+
+- Kelly, J.L. (1956). "A New Interpretation of Information Rate" — The original paper
+- Thorp, E.O. "The Kelly Criterion in Blackjack, Sports Betting, and the Stock Market" — Practical applications
+
+---
+
+*PR3DICT Documentation*