Leak-Snipe-Beta

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