# LottoSight

A desktop application for analysing historical lottery draw data and generating statistically-informed number predictions.

Built with Python and Tkinter. Runs entirely offline — no accounts, no subscriptions, no cloud. All data is stored in a local SQLite database.

---

## Features at a glance

| Category | Highlights |
|---|---|
| **Data** | Auto-fetches from 6 live sources on launch and every 24 hours |
| **History** | Searchable, filterable, sortable draw history table |
| **Analysis** | 8 chart types — frequency, gaps, heatmap, pairs, odd/even, sums, deltas, odds |
| **Prediction** | 7 strategies with recency weighting and combination-quality filtering |
| **Checking** | Compare any ticket against the full draw history |
| **Wheeling** | Full-cover wheeling up to 200 tickets |
| **Export** | Excel and CSV export for draws, predictions, and frequency data |
| **Import** | Import draw history from CSV files |
| **Backup** | One-click database backup and restore |

---

## Supported games

| Game | Balls | Pool | Bonus | Source |
|---|---|---|---|---|
| Powerball | 5 | 1–69 | 1 (1–26) | NY Open Data API |
| Mega Millions | 5 | 1–70 | 1 (1–25) | NY Open Data API + Texas Lottery CSV |
| Cash 5 (VA) | 5 | 1–45 | — | Virginia Lottery API |
| Millionaire for Life (VA) | 5 | 1–58 | 1 (1–5) | Virginia Lottery API |
| Bank a Million (VA) | 6 | 1–40 | 1 (1–40) | Virginia Lottery API |

Custom games with configurable ball counts and pools can also be added.

---

## Screens

### Dashboard
The home screen shown on launch. Displays:
- Most recent draw result per game (numbers, bonus, multiplier, top prize)
- Next scheduled draw date for Powerball and Mega Millions
- Hot numbers — top 5 most frequent in the last 100 draws
- Most overdue numbers — highest gap since last appearance
- Database summary — total draw count and saved predictions per game
- Game filter to focus all sections on a single game

### History
Full draw history browser with:
- Filter by game, date range, or a specific number
- Sort by any column (date, numbers, bonus, multiplier, source)
- Ball display strip for the selected row
- Export the filtered view to Excel or CSV

### Analysis
Eight chart tabs, all game-selectable with a frequency window slider:

| Tab | What it shows |
|---|---|
| Frequency | Bar chart — how often each number has appeared |
| Positional | Heatmap — frequency broken down by draw position |
| Gaps | Bar chart — draws since each number last appeared (blue = recent, red = overdue) |
| Pairs | Horizontal bar — top-20 most common two-number combinations |
| Odd/Even | Bar chart — distribution of odd vs even split per draw |
| Sum Range | Histogram — distribution of draw totals |
| Deltas | Bar chart — gaps between consecutive numbers within draws |
| Odds | Table — prize tiers with exact odds and probability (no chart, no matplotlib) |

All chart tabs include a Matplotlib navigation toolbar for zoom and pan. The Frequency chart data can be exported to Excel from this screen.

### Predictor
Four tabs:

**Generate** — pick a game, strategy, and ticket count, then generate tickets. An optional Exclude field lets you block specific numbers. All strategies apply combination-quality filters automatically (see below). Results show as colour-coded lottery balls. Generated tickets can be saved to the database or copied to clipboard.

**Saved** — browse all predictions stored in the database, filtered by game. Shows how many numbers each prediction matched against the most recent real draw. Supports deleting selected rows or clearing all predictions.

**Check Ticket** — enter your own numbers and bonus ball, then compare against the entire draw history. Results table shows draw date, draw numbers, main hits, bonus hit, and prize tier. Rows are colour-coded: purple for jackpot, green for ≥3 matches, grey otherwise.

**Wheel** — enter a pool of numbers and a pick size; generates every C(n, k) combination up to a cap of 200 tickets. Live preview shows the ticket count before generating. Results can be saved to the database or copied to clipboard.

### Settings
- Enable or disable games (disabled games are hidden everywhere)
- Add custom games with configurable parameters
- Delete custom games (protected if draw records exist)
- Import draw history from a CSV file per game
- Manual fetch button with last-fetch status per source
- Database backup (timestamped copy) and restore
- Fetch interval display (24 hours, runs automatically)

---

## Prediction strategies

All strategies apply three combination-quality filters after generation, retrying or swapping numbers as needed:

- **All-even / all-odd** — rejected when the ticket has 4 or more numbers and all share the same parity
- **4+ consecutive** — rejected if the sorted ticket contains a run of four or more consecutive integers
- **Sum outlier** — rejected if the total falls outside the historical 10th–90th percentile (requires ≥10 draws in the database)

| Strategy | Description |
|---|---|
| **Ensemble** | Runs all five core strategies and picks numbers with the most cross-strategy votes. Consensus numbers appear in multiple independent analyses. |
| **Hot Numbers** | Top-frequency numbers from the last 100 draws, weighted so recent draws contribute more than older ones (exponential decay, half-life ≈ 69 draws). |
| **Due Numbers** | Numbers with the largest gap since their last appearance — most overdue relative to expected frequency. |
| **Weighted Random** | Random draw with probability proportional to recency-adjusted historical frequency. Retries until a combination passes all filters. |
| **Monte Carlo** | Runs 10,000 weighted-random simulations and returns the numbers selected most often. |
| **Positional** | Selects the most frequent number at each draw position (position 1, 2, 3 …). |
| **Quick Pick** | Pure random selection. No historical data required. |

---

## Data fetch

Draws are fetched automatically on app launch and every 24 hours in a background thread. A **Fetch Now** button in the toolbar triggers an immediate fetch.

Sources are incremental for Virginia Lottery games — only draws newer than the most recent record in the database are processed, so repeat fetches complete quickly regardless of total history size.

After each fetch that adds new draws, saved predictions are automatically compared against the latest draw. A match alert appears in the status bar if any prediction matched two or more main numbers or the bonus ball.

---

## Getting started

### Requirements
- Python 3.12 or higher
- Windows (Tkinter + truststore for SSL; other platforms untested)

### Run from source

```bash
# Install dependencies
pip install -r requirements.txt

# Launch the app
python main.py
```

The database is created automatically at `data/lottosight.db` on first launch. Draw data is fetched from live sources on startup.

### Build a standalone executable

```powershell
# Full build (installs deps, then builds)
.\build.ps1

# Skip pip install on repeat builds
.\build.ps1 -SkipDeps

# Clean build (wipes dist\ and build\ first)
.\build.ps1 -Clean
```

Or double-click `build.bat` from Explorer. Output lands in `dist\LottoSight\LottoSight.exe` (~111 MB folder).

---

## Project structure

```
lottosight/
├── main.py                  # Entry point, main window, auto-fetch wiring
├── build.ps1                # Build script (PyInstaller)
├── build.bat                # Double-click wrapper for build.ps1
├── lottosight.spec          # PyInstaller spec file
├── requirements.txt
├── db/
│   ├── database.py          # SQLite init, schema, migrations, backup/restore
│   └── models.py            # CRUD operations
├── core/
│   ├── analyzer.py          # All analysis functions (frequency, gaps, pairs, …)
│   ├── predictor.py         # 7 prediction strategies
│   ├── filters.py           # Combination-quality filters
│   ├── checker.py           # Ticket checker — compare against draw history
│   ├── fetcher.py           # Fetch logic for all 6 data sources
│   ├── importer.py          # CSV import parser
│   ├── exporter.py          # Excel/CSV export + icon generator
│   ├── odds.py              # Prize tier odds calculator
│   ├── wheeling.py          # Full-cover wheel generator
│   └── paths.py             # Frozen/dev path resolution
├── ui/
│   ├── dashboard.py         # Home screen
│   ├── history.py           # Draw history browser
│   ├── analysis.py          # Charts and analysis screen
│   ├── predictor_ui.py      # Prediction generator (4 tabs)
│   ├── settings.py          # Settings screen
│   ├── statusbar.py         # Bottom status bar
│   └── widgets.py           # BallsBar canvas widget
├── tests/                   # 451 tests (pytest)
└── assets/
    └── icon.png
```

---

## Tech stack

| Component | Library |
|---|---|
| UI | Tkinter + ttk |
| Charts | Matplotlib (embedded via FigureCanvasTkAgg) |
| Database | SQLite via sqlite3 |
| HTTP | requests |
| Analysis | numpy, collections, itertools |
| Scheduler | APScheduler |
| Export | openpyxl |
| SSL (Windows) | truststore |
| Packaging | PyInstaller |

---

## Running tests

```bash
pytest tests/
```

451 tests covering database models, fetch logic, all analysis functions, all prediction strategies, combination filters, ticket checker, wheeling, import/export, and UI smoke tests.