# Accuracy Validation

GGSight must not be treated as launch-ready until the scanner is validated against labeled local screenshots.

## Dataset

The local dataset lives in `test_data/`. Each image must have a matching JSON file with the same stem.

Required label fields:

- `game`
- `resolution`
- `source_type`
- `scan_zone`
- `expected_names`
- `expected_raw_text`

Optional fields include `notes`, `capture_mode`, `ui_scale`, `background`, and `ocr_fixture_text`.

Do not publish copyrighted gameplay screenshots unless redistribution is permitted. Use `tools/import_dataset_sample.py` to import authorized local samples.

## Run A Report

Parser-only baseline using label fixture text:

```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 report:

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

## Metrics

The report calculates:

- Precision.
- Recall.
- F1 score.
- Exact gamer-tag match rate.
- Character error rate.
- False-positive rate.
- False-notification rate.
- Lookup latency.
- OCR processing latency.
- Number of detected names.
- Number of missed names.
- Number of incorrect names.

Reports are grouped by game, scan zone, resolution, capture source, OCR engine, and preprocessing configuration.

## MVP Targets

- 95% or greater precision for lobby and scoreboard names.
- 85% or greater recall for fast-moving kill-feed names.
- Fewer than one incorrect notification per hour.
- No profile marked confirmed from OCR evidence alone.
- High-confidence identity results require multiple matching signals.
- Cached lookup results should usually appear within one second.
- Uncached lookup results should generally appear within five seconds.

## Current Status

The checked-in synthetic samples are non-copyrighted plumbing fixtures, not proof of real-world OCR performance. Real Fortnite and Call of Duty screenshots must be imported locally and evaluated before claiming readiness.


