# GGSight

GGSight is a screen-only gaming companion for personal encounter history and public gamer tag lookup. It scans visible pixels from user-selected screen zones, runs OCR, extracts likely gamer tags, checks configured public sources, scores evidence, and stores local encounter history.

GGSight does not read game memory, inspect packets, hook into games, inject overlays, automate gameplay, modify files, bypass streamer mode, reveal hidden lobby data, or interact with anti-cheat systems.

Core product: detect visible gamer tags, verify who they are, and notify the player when something meaningful is found.

Business model: useful Free tier plus a no-card Pro trial. Free limits verified public-profile lookups, not basic visible-screen detection.

## MVP Features

- Static marketing website under `website/` with home, download, pricing, supported games, FAQ, privacy, terms, contact, and blog placeholder pages.
- Desktop distribution flow under `desktop/` with install instructions, account strategy, and update metadata.
- Backend-only authentication and password rules under `docs/AUTHENTICATION.md`.
- PySide6 desktop app with first-launch agreement.
- Fortnite, Call of Duty, Apex Legends, Valorant, and Rocket League JSON game profiles.
- Research-backed scan-zone map for visible player-name surfaces.
- Drawn scan zones for lobby/feed/scoreboard-style regions.
- Screenshot upload and live visible-screen region scanning.
- OCR preprocessing with `pytesseract`.
- Gamer tag parser with clan tag support, action-word filtering, and duplicate cleanup.
- SQLite encounter history, scan zones, matches, and lookup results.
- Manual search for OCR failures.
- API-key settings for public lookup sources.
- Confidence scoring and desktop notifications.
- CSV export and JSON backup helpers.
- Privacy controls for local-only mode, blocklist, and history deletion.
- Safety tests that check for forbidden imports and primitives.
- Labeled OCR dataset system under `test_data/`.
- Accuracy report generator with precision, recall, F1, exact match rate, character error rate, false-positive rate, latency, and grouped results.
- Multi-frame OCR stabilization before live lookup.
- GGSight verified gamer-tag directory.
- Separate OCR, identity, and source confidence values.
- Live Mode and Post-Match Mode display policies.
- User correction and incorrect-profile reporting workflow.
- Privacy preview and performance diagnostics plumbing.

## Website

Open `website/index.html` in a browser to review the marketing site. The site positions GGSight as a downloadable Windows desktop app and does not claim browser-only scanning.

## Desktop Distribution

Desktop distribution notes live in `desktop/README.md`. The MVP update checker reads `desktop/update_metadata.json`.

## Install

```powershell
cd C:\Users\glenr\Documents\Codex\2026-07-06\weatherpromise-plugin-weatherpromise-openai-curated-remote\outputs\GGSight
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

Install Tesseract OCR separately and make sure the `tesseract` executable is on your PATH:

- Windows installer: <https://github.com/UB-Mannheim/tesseract/wiki>
- macOS: `brew install tesseract`
- Linux: use your distro package manager, such as `sudo apt install tesseract-ocr`

## Run

```powershell
python -m ggsight.app
```

The first launch shows the required legal agreement. Settings and the SQLite database are stored in `.ggsight-data` under the current working directory unless `GGSIGHT_DATA_DIR` is set.

## Basic Use

1. Select a game profile, such as Fortnite or Call of Duty.
2. Select a source type: entire monitor, selected region, window title, OBS preview, capture card preview, PS Remote Play, or Xbox Remote Play.
3. Click **Draw Zone** and draw a rectangle over visible screen text.
4. Click **Start Scan**.
5. Watch the dashboard for detected players, seen-before status, confidence, and lookup links.

## Screenshot OCR

Use **Upload Screenshot** to test screenshots before live scanning. This is the fastest way to tune OCR and parser behavior for a specific scoreboard or feed.

## Manual Search

Use **Manual Search** when OCR misses a gamer tag. Add a public profile URL if you already have one, or leave it blank to use configured public sources.

## Fortnite Profile

The Fortnite profile includes zones for:

- `bus_driver_feed`
- `kill_feed`
- `knock_feed`
- `party_panel`
- `team_roster`
- `social_panel`
- `spectating_name`
- `eliminated_by_banner`
- `reboot_card_banner`
- `ranked_leaderboard`
- `end_match_screen`

Default ignored words include `thanked`, `bus`, `driver`, `eliminated`, `knocked`, `with`, `joined`, and `left`.

## Call of Duty Profile

The Call of Duty profile includes zones for:

- `pregame_lobby`
- `party_roster`
- `team_roster`
- `kill_feed`
- `elimination_banner`
- `deathcam_killed_by`
- `spectating_banner`
- `scoreboard`
- `post_match_scoreboard`
- `recent_squad_panel`
- `end_match_summary`

Default ignored words include `killed`, `eliminated`, `joined`, `left`, `match`, `loading`, `scoreboard`, `operator`, and `weapon`.

## Apex Legends Profile

The Apex Legends profile includes zones for:

- `legend_select_roster`
- `champion_squad`
- `kill_feed`
- `squad_panel`
- `squad_banner`
- `death_box_banner`
- `spectating_banner`
- `death_recap`
- `mixtape_scoreboard`
- `end_match_summary`

## Valorant Profile

The Valorant profile includes zones for:

- `agent_select_roster`
- `loading_match_roster`
- `kill_feed`
- `scoreboard`
- `combat_report`
- `round_result_banner`
- `post_match_scoreboard`

## Rocket League Profile

The Rocket League profile includes zones for:

- `scoreboard`
- `post_goal_scoreboard`
- `goal_replay_banner`
- `team_roster`
- `nameplates`
- `post_match_scoreboard`
- `party_panel`

See `docs/SCAN_ZONE_RESEARCH.md` for the deeper game-by-game target map and source links.

## Console Mode

GGSight does not connect to consoles directly. Open a PC-visible capture card preview, OBS preview, PS Remote Play window, or Xbox Remote Play window, then draw scan zones over that visible window.

## OCR Troubleshooting

- Use high-contrast capture zones.
- Keep boxes tight around text, not the whole screen.
- Prefer static scoreboard/end-match screens for initial testing.
- Increase source resolution if Tesseract confuses `O/0`, `I/l/1`, or `B/8`.
- Use manual search for failed reads.

## Tests

```powershell
pytest
```

The test suite covers parsing, normalization, confidence scoring, database behavior, mocked lookup behavior, exports, and safety constraints.

## Accuracy Reports

Parser-only fixture baseline:

```powershell
python -m ggsight.accuracy_report test_data --ocr-engine fixture --json-out outputs\accuracy_report.json --md-out outputs\accuracy_report.md
```

Real OCR validation with Tesseract:

```powershell
python -m ggsight.accuracy_report test_data --ocr-engine pytesseract --json-out outputs\accuracy_report.json --md-out outputs\accuracy_report.md
```

The checked-in samples are synthetic fixtures. Import authorized gameplay screenshots locally before making product-readiness claims.

