Content
<div align="center">
# 🃏 LeakSnipe
**A local-first poker study workstation that turns hand histories into reliable statistics, replayable decisions, opponent reads, range work, and AI-assisted review.**
[](https://leaksnipe.win)
[](#requirements)
[](#architecture)
[](#roadmap)
> **Track → Find → Review → Study → Improve**
</div>
---
## ⚖️ LICENSE & TERMS
**LEAKSNIPE PROPRIETARY SOFTWARE LICENSE**
Copyright (c) 2026 Mauro Mark Nazareno Fanelli. All rights reserved.
**LeakSnipe and all source code, algorithms, data models, databases, MCP connectors, APIs, documentation, and UI components are the exclusive property of Mauro Mark Nazareno Fanelli.**
- ✅ **Permitted:** Personal poker hand review, analysis, research, and study only.
- ❌ **Prohibited:** Commercial use, redistribution, modification, reverse engineering, credential sharing, and live-play real-money usage without written authorization.
- 🔒 **Confidentiality:** Non-public portions (source, architecture, credentials, endpoints) are confidential and must not be disclosed without prior written permission.
**For the full license text, see [LICENSE](LICENSE).**
---
LeakSnipe watches your poker client's hand-history files, imports them into a local SQLite database in real time, and connects the full review loop in one desktop app: a live HUD while you play, statistics and opponent reads afterward, a hand replayer to walk back through key spots, and equity/range/theory tools grounded in real math — with optional AI coaching on top.
**Primary target: [CoinPoker](https://www.coinpoker.com/).** LeakSnipe also imports and HUDs BetACR, Americas Cardroom (ACR), and WPN hand histories, but CoinPoker is where the live-import, live-HUD, and tournament-tracking work gets the most attention.
The canonical application is the React/Tauri interface in `leaksnipe-ui/`, backed by the FastAPI service in `sidecar/server.py` and the Python analysis engine at the repository root. The original `poker_gui.py` desktop application remains available as a fallback and powers the primary Windows live HUD.
## Start here
- [Product introduction](docs/INTRODUCTION.md)
- [Theory tooling and accuracy boundaries](docs/THEORY.md)
- [Product feature audit and roadmap](docs/PRODUCT_FEATURE_AUDIT.md)
- [Architecture & web docs](docs/index.html)
## Contents
- [Capabilities](#what-leaksnipe-does)
- [Application tour](#application-tour)
- [Architecture](#architecture)
- [Repository layout](#repository-layout)
- [Installation](#installation)
- [Live HUD setup](#live-hud-setup)
- [AI configuration and privacy](#ai-configuration-and-privacy)
- [Developer workflow](#developer-workflow)
- [Validation, tests, and security scanning](#validation-tests-and-security-scanning)
- [Troubleshooting](#troubleshooting)
- [Accuracy and scope](#accuracy-and-scope)
- [Contributing](#contributing)
## What LeakSnipe does
### Hand tracking and review
- Imports hand-history files from configured watch folders, including CoinPoker's rotating `main.log` chain and BetACR/ACR/WPN `.txt`/`.ots` files.
- Automatically discovers common CoinPoker and BetACR/ACR/WPN hand-history locations.
- Stores hands locally in `poker_hands.db` using versioned SQLite migrations.
- Shows hero cards, board cards, result, position, pot, table, date, and tags.
- Opens hand statistics on a single click.
- Opens the detailed hand view/replayer on double-click or through **Replay**.
- Replays every street and action with an opponent-hole-card visibility toggle.
- Supports safe re-imports and incremental background watching.
- Derives tournament-level rollups directly from hand data when a site (like CoinPoker) never emits a separate tournament-summary file.
### Statistics and opponent analysis
- Tracks VPIP, PFR, aggression factor, fold-to-c-bet, WTSD, and 3-bet statistics.
- Breaks opponent VPIP/PFR down by UTG, MP, HJ, CO, BTN, SB, and BB positions.
- Persists indexed positional facts instead of recomputing every HUD request.
- Shows sample sizes alongside percentages.
- Provides player classification, leak alerts, and position-level summaries.
- Supports manual opponent tagging (notes, colors, custom labels) alongside auto-classification.
- Refreshes opponent HUD data on focus and during longer review sessions.
### Live Windows HUD
- Uses the original Python/pywin32 overlay for the primary live HUD.
- Anchors overlays to the active table window — CoinPoker tables (detected via the running process, not just window title) and supported ACR/BetACR/WPN tournament tables alike.
- Rotates seats around the hero and adapts as players join, leave, or switch tables.
- Shows readable opponent badges and position-specific VPIP/PFR.
- Supports locked click-through mode, unlocked dragging, persistent offsets, and reset controls.
- Hides when no matching poker table is present.
The Tauri transparent overlay remains experimental. Do not run both HUD implementations simultaneously.
### AI-assisted analysis
- Produces street-by-street hand review grounded in parsed actions and computed facts.
- Supports session analysis, coaching chat, local memory, and database-query tools.
- Uses ASI:One as the preferred provider when configured, with Cloudflare AI Gateway support.
- Supports separate ASI:One keys for hand analysis and coach/chat concurrency.
- Supports OpenAI, Gemini, Anthropic, DeepSeek, and optional local Ollama alternatives.
- Makes web research optional: **Off**, **On-demand**, or **Always**.
- Keeps routine hand analysis and simple statistics local unless a provider call is requested.
AI explanations are not used as a substitute for poker math. Equity percentages are computed by the local engine.
### Equity, pot odds, and theory
- Monte Carlo equity for:
- No-Limit Hold'em
- Pot-Limit Omaha (with an ISMCTS live-decision solver)
- Omaha Hi-Lo 8-or-better
- Seven-card stud
- Seven-card stud hi-lo
- Multi-way pot-odds calculations.
- Tournament ante and ICM support in theory inputs.
- CFR+ experiments for small exact or abstracted poker games, plus ReBeL/Pluribus-style architectural scaffolds for coaching (not a claim of superhuman multiplayer play).
- Lightweight neural value estimates trained from computed samples.
- Stack-depth charts at 5, 10, 25, 35, 50, 75, and 100 BB.
- Range Studio with predefined charts, editable 13×13 matrices, mixed frequencies, custom action colors, comparison, and local chart persistence.
See [docs/THEORY.md](docs/THEORY.md) for the important distinction between exact equity, abstracted CFR strategy, approximated charts, and AI explanation.
## Application tour
| Area | Purpose |
|---|---|
| **Hands** | Browse imported hands, inspect board cards and results, open opponent statistics, and replay a hand. |
| **Opponents** | Tag, note, and color-code opponents; view auto-classification alongside manual reads. |
| **Stats** | Review aggregate and positional performance, sample sizes, and leak alerts. |
| **AI Coach** | Analyze sessions or hands, ask grounded questions, and optionally request cited web research. |
| **Equity** | Run local Monte Carlo calculations across supported poker variants. |
| **Theory** | Explore CFR+, neural values, stack charts, and Range Studio. |
| **Settings** | Configure hero aliases, watch folders, AI routing, HUD behavior, and runtime diagnostics. |
## Architecture
### Level 1: System Overview
```mermaid
graph TD
subgraph Client ["Desktop Client Layer"]
UI["Tauri React Frontend (Port 1420)"]
HUD["Live HUD Overlay Badge"]
end
subgraph Sidecar ["Local Sidecar Engine"]
API["FastAPI Sidecar (Port 8765)"]
SQLite[("poker_hands.db (SQLite WAL)")]
SyncWatcher["sync_hands.py Watcher"]
end
subgraph Cloud ["Cloudflare Edge Infrastructure"]
Worker["leaksnipe Worker (worker.leaksnipe.win/mcp)"]
KV[("HAND_META KV Namespace")]
R2[("Tiered R2 Hand-History Buckets")]
D1[("leaksnipe-hands D1 Database")]
end
UI <--> API
HUD <--> API
API <--> SQLite
SyncWatcher --> SQLite
SyncWatcher -- "Batch Upload" --> Worker
Worker <--> KV
Worker <--> R2
Worker <--> D1
```
### Level 2: Real-time Hand History Sync Dataflow
```mermaid
sequenceDiagram
autonumber
participant PokerSite as Poker Client (CoinPoker / ACR)
participant Importer as Importer / Directory Watcher
participant DB as SQLite (poker_hands.db)
participant Sync as sync_hands.py
participant Worker as Cloudflare Worker (/mcp)
participant R2 as Cloudflare R2
participant KV as Cloudflare KV (HAND_META)
PokerSite->>Importer: Writes Hand History File (.log / .txt)
Importer->>DB: Parses and Stores Hand & Actions
Sync->>DB: Queries Unsynced, Completed Hands
Sync->>Worker: POST /mcp (store_large_hand_history)
Worker->>R2: Saves Full Hand History JSON Object
Worker->>KV: Stores Metadata Index (meta:handId)
Sync->>DB: Updates _cloudflare_sync Table Status
```
### Level 3: Cloudflare MCP & AI Reasoning Protocol
```mermaid
flowchart LR
subgraph ClientApp ["AI Client / Desktop UI"]
Prompt["User Request / Coach Query"]
end
subgraph MCPWorker ["Cloudflare MCP Endpoint"]
Router["JSON-RPC Tool Router"]
Tools["Tools: list_hand_histories | get_hand_history | d1_database_summary"]
end
subgraph Storage ["Cloudflare Data Tier"]
D1DB[("D1 SQL Database")]
KVNS[("KV Meta Index")]
R2Storage[("R2 Object Buckets")]
end
subgraph AI ["AI Engine"]
LLM["Configured AI Provider"]
end
Prompt --> Router
Router --> Tools
Tools --> D1DB
Tools --> KVNS
Tools --> R2Storage
Storage --> Router
Router --> LLM
LLM --> Prompt
```
The split is intentional:
- **Rust/Tauri** owns the desktop shell, process supervision, and native commands.
- **React/TypeScript** owns the primary application interface.
- **FastAPI/Python** exposes the existing poker engine through a local HTTP API.
- **SQLite** remains the local source of truth and requires no database server.
- **Python/pywin32** owns the production live-table overlay.
The local sidecar listens on `127.0.0.1:8765`. Tauri can supervise it directly or reuse the launcher-managed process.
## Repository layout
| Path | Role |
|---|---|
| `leaksnipe-ui/` | Canonical React + Tauri v2 desktop application. |
| `leaksnipe-ui/src-tauri/` | Rust process supervision, Tauri commands, ACL, and experimental overlay support. |
| `sidecar/server.py` | FastAPI application and local REST API. |
| `models.py` | Hand model, SQLite access, and persistence integration. |
| `db_migrations.py` | Versioned schema migrations and positional-fact reconciliation. |
| `parsers.py`, `importing.py` | Site parsing (CoinPoker, BetACR/ACR/WPN), hand discovery, imports, and background watching. |
| `analysis.py` | Player statistics, leak analysis, and analysis facts. |
| `equity.py`, `pot_odds.py` | Local poker math engines. |
| `ai_processor.py` | AI provider routing, tools, prompts, and grounded analysis. |
| `coach_memory.py`, `dataset_context.py`, `web_context.py` | Coach memory and optional context sources. |
| `theory/` | CFR+, charts, and neural value tooling. |
| `poker_gui.py` | Maintained CustomTkinter fallback and primary Python live HUD. |
| `scripts/` | Install, launch, supervision, and developer PowerShell scripts. |
| `tools/` | Standalone maintenance utilities (DB merge, Cloudflare/Drive sync helpers) run manually, not imported by the app. |
| `tests/` | Python regression and theory tests. |
| `docs/` | Product, architecture, security, and theory documentation. |
| `debug/` | Captured log/sample artifacts kept for reference while debugging parsers — not read by any code path. |
| `mcp-server/` | Cloudflare Worker exposing the MCP tool endpoint at `worker.leaksnipe.win/mcp`. |
| `leak-snipe-desktop/`, `PokerBuild/` | Older/incomplete experiments; not the canonical app. |
Web-search modes:
| Mode | Behavior |
|---|---|
| **Off** | Never request web context. |
| **On-demand** | Search only when the user explicitly requests research or current sources. |
| **Always** | Allow web context for coach requests. |
Local data stays on the machine unless a feature explicitly sends context to a configured AI or web provider. Review provider privacy policies before enabling cloud analysis.
## Data and migrations
Default local data files:
| File | Contents |
|---|---|
| `poker_hands.db` | Imported hands, actions, players, tags, cached player types, and positional facts. |
| `coach_memory.db` | Local AI coach memory. |
| `settings.json` | Local application settings and HUD positions. |
`db_migrations.py` applies versioned, idempotent migrations at startup. It also reconciles missing positional facts after rolling restarts. SQLite uses WAL mode and a busy timeout so the sidecar and Python HUD can safely share the local database.
Back up `poker_hands.db` before manually editing it. API keys belong only in `.env`, never in the database or `settings.json`.
Runs a Bandit static-analysis pass over the Python codebase locally — useful as a substitute when GitHub Actions-based scanning (CodeQL or otherwise) isn't available.
## Local API overview
FastAPI exposes interactive schemas at `/docs`. Important routes include:
| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/health` | Lightweight sidecar health and runtime identity. |
| `GET` | `/api/diagnostics` | Database schema, process, version, and path diagnostics. |
| `GET` | `/api/hands` | Paginated imported hands. |
| `GET` | `/api/hands/{hand_id}` | Complete hand detail and replay data. |
| `GET` | `/api/players/{name}/stats` | Overall and positional opponent statistics. |
| `GET` | `/api/tournaments/rollup` | Tournament summary derived from hand data (covers sites with no separate results export). |
| `POST` | `/api/import/scan` | Scan configured hand-history folders. |
| `GET` | `/api/ai/status` | Non-secret AI routing status. |
| `POST` | `/api/ai/reload` | Reload `.env` and provider configuration. |
| `POST` | `/api/analyze/hand` | Grounded street-by-street hand analysis. |
| `POST` | `/api/chat` | AI coach conversation. |
| `POST` | `/api/equity` | Hold'em Monte Carlo equity. |
| `POST` | `/api/equity/omaha8` | Omaha Hi-Lo equity. |
| `POST` | `/api/equity/stud` | Seven-card stud equity. |
| `POST` | `/api/equity/stud8` | Stud hi-lo equity. |
| `GET` | `/api/theory/charts` | Stack-depth chart data. |
| `POST` | `/api/theory/cfr` | Run a supported CFR+ subgame. |
## Contributing
Contributions are limited to automated workflows and approved entities only.
## Code Quality — Sourcery AI
This repository uses [Sourcery AI](https://sourcery.ai) for automated code review and refactoring suggestions. Sourcery analyses every pull request and posts inline comments with improvement suggestions.
### How it works
- **Pull request reviews**: Sourcery posts inline review comments automatically whenever a PR is opened or updated (see `.github/workflows/sourcery.yml`).
- **Configuration**: Rules and thresholds are defined in `.sourcery.yaml` at the repository root.
### Run Sourcery locally
```bash
# Install the Sourcery CLI
pip install sourcery-cli
# Authenticate (one-time, uses your Sourcery account token)
sourcery login --token <YOUR_SOURCERY_TOKEN>
# Review all Python files in the repo
sourcery review .
# Review only files changed in your current branch vs. master
sourcery review --diff "git diff master"
# Apply safe auto-fixes in place
sourcery review --fix .
```
### GitHub secret required
The GitHub Actions workflow requires a repository secret named **`SOURCERY_TOKEN`**.
Add it at: `Settings → Secrets and variables → Actions → New repository secret`.
Obtain your token from [app.sourcery.ai/account](https://app.sourcery.ai/account).
## Roadmap
The current roadmap focuses on:
- database-backed hand filters and saved reports
- review-to-study links from a hand into the nearest covered range
- drill generation and progress history
- board-texture aggregate reports
- larger but explicitly abstracted solver coverage
- optional service/database scaling after local correctness is established
See [docs/PRODUCT_FEATURE_AUDIT.md](docs/PRODUCT_FEATURE_AUDIT.md) for the detailed competitive analysis and implementation sequence.
## Security
See [docs/SECURITY.md](docs/SECURITY.md) for the vulnerability-reporting process.
## License
No license file is currently included in this repository. Unless the maintainer adds one, the source is publicly visible but no open-source license is granted.
## Maintainer
- Organization: [WalkerEnterprise](https://github.com/WalkerEnterprise)
- Repository: [WalkerEnterprise/Leak-Snipe-Beta](https://github.com/WalkerEnterprise/Leak-Snipe-Beta)
