hotgaze 0.1.0__tar.gz

hotgaze-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+# HotGaze CI
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev deps
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy type check
+        run: mypy src/
+
+      - name: Pytest (no perf, no deep)
+        run: pytest -m "not perf and not deep"

hotgaze-0.1.0/.github/workflows/nightly.yml

@@ -0,0 +1,48 @@
+# HotGaze nightly — deep backend tests
+#
+# Runs pytest -m deep on a schedule. Because UNISAL weights are not yet
+# published (see PROGRESS.md Orchestrator TODOs), deep tests skip with a
+# reason — nightly is expected to be green-by-skip until weights are live.
+# Once weights are published, this workflow will exercise the full deep
+# pipeline nightly.
+#
+# Weight cache is persisted via actions/cache, keyed by the checksums
+# recorded in LICENSES-THIRD-PARTY.md.
+
+name: Nightly
+
+on:
+  schedule:
+    - cron: "0 3 * * *"  # 3 AM UTC daily
+  workflow_dispatch:  # allow manual trigger
+
+jobs:
+  deep:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache weight files
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/hotgaze
+          key: hotgaze-weights-${{ hashFiles('LICENSES-THIRD-PARTY.md') }}
+          restore-keys: hotgaze-weights-
+
+      - name: Install package with deep deps
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -e ".[deep,dev]"
+
+      - name: Pytest deep
+        run: pytest -m deep -v

hotgaze-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+# HotGaze release pipeline
+#
+# On tag push (v*), builds sdist + wheel and publishes to PyPI via
+# trusted publishing.  No tokens or secrets needed — PyPI trusts this
+# repo + workflow combination after one-time setup by the orchestrator.
+#
+# Prerequisites (orchestrator, do before first tag push):
+#   1. Create the weights-v1 GitHub Release with 4 assets.
+#   2. Configure PyPI trusted publishing:
+#        PyPI → Settings → Publishing → Add → repo: suryakosaraju/hotgaze,
+#        workflow: release.yml, environment: (leave blank).
+#   3. Push a v* tag (e.g. v0.1.0).
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: python3 -m pip install --upgrade pip build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hotgaze-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml
+
+# HotGaze cache (local testing)
+.hotgaze-cache/
+
+# Test fixtures (generated on demand by conftest.py)
+tests/fixtures/*.png
+
+# Vendored-model backbone weights (downloaded on first use, never committed)
+src/hotgaze/_unisal/weights/
+*.pth.tar
+CLAUDE.md
+DESIGN.md
+PLAN.md
+PROGRESS.md
+CONTRIBUTING.md
+CONTRIBUTING.md
+docs/devlog*.md

hotgaze-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to HotGaze will be documented in this file.
+
+## v0.1.0 (2026-07-16)
+
+Initial release.
+
+### Features
+- **Fast heuristic backend**: spectral-residual saliency + Sobel contrast + center-bias prior + F-pattern gaze flow. Zero downloads, fully offline, sub-second on CPU.
+- **Deep saliency backend** (`--backend deep`): UNISAL pretrained model (Apache 2.0), CPU-only, deterministic per-machine. Requires `pip install hotgaze[deep]` and one-time weight download.
+- **Region scoring**: `hotgaze score IMG --region name:x,y,w,h --json` → canonical JSON with attention share, peak value, and rank per region.
+- **A/B comparison**: `hotgaze compare A.png B.png [--region ...]` → per-region attention-share deltas + 3×3 spatial grid + focal-point movement.
+- **Focal points**: local maxima via OpenCV dilate-based max-filter, ranked by attention value.
+- **Faces layer** (`--layers faces`): YuNet face detector (MIT) adds Gaussian attention blobs over detected faces. Default weight 0.50 — tuned so enabling the layer shifts the focal point onto detected faces on portraits; zero effect on faceless UI images.
+- **Canonical JSON**: schema v1, sorted keys, floats rounded to 6 dp, byte-identical across runs on the same machine.
+- **CLI**: `hotgaze run`, `hotgaze score`, `hotgaze compare`, `hotgaze info`.
+- **Weight manager**: download-on-first-use with SHA-256 verification, atomic cache, `click.progressbar`.
+- **Offline-first**: default pipeline works with zero network access; deep backend caches weights after one fetch.

hotgaze-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surya Kosaraju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hotgaze-0.1.0/LICENSES-THIRD-PARTY.md

@@ -0,0 +1,132 @@
+# Third-Party Licenses
+
+This file records every third-party dependency bundled or used by HotGaze,
+as required by the project's license-hygiene policy (see CLAUDE.md).
+
+## Core runtime dependencies
+
+| Package | Version (min) | URL | License | Notes |
+|---------|--------------|-----|---------|-------|
+| numpy | 1.24 | https://github.com/numpy/numpy | BSD-3-Clause | Array computation |
+| opencv-python-headless | 4.8 | https://github.com/opencv/opencv-python | Apache-2.0 | Image I/O, base OpenCV (no contrib) |
+| pillow | 10.0 | https://github.com/python-pillow/Pillow | HPND (historical) | Image loading |
+| click | 8.1 | https://github.com/pallets/click | BSD-3-Clause | CLI framework |
+| pydantic | 2.0 | https://github.com/pydantic/pydantic | MIT | Config models, validation |
+
+## Optional runtime dependencies
+
+| Package | Version (min) | URL | License | Notes |
+|---------|--------------|-----|---------|-------|
+| torch | 2.0 | https://github.com/pytorch/pytorch | BSD-3-Clause | Deep saliency backend (`hotgaze[deep]`) |
+
+## Development dependencies
+
+| Package | Version (min) | URL | License | Notes |
+|---------|--------------|-----|---------|-------|
+| ruff | 0.4 | https://github.com/astral-sh/ruff | MIT | Lint + format |
+| pytest | 8.0 | https://github.com/pytest-dev/pytest | MIT | Test framework |
+| pytest-cov | 5.0 | https://github.com/pytest-dev/pytest-cov | MIT | Coverage reporting |
+| mypy | 1.8 | https://github.com/python/mypy | MIT | Static type checking |
+| scikit-image | 0.22 | https://github.com/scikit-image/scikit-image | BSD-3-Clause | **TEST-ONLY** — astronaut face fixture (BSD). Must never be imported from `src/` |
+| actionlint-py | 1.7 | https://github.com/Mateusz-Grzelinski/actionlint-py | MIT | CI workflow linting |
+
+## Pretrained models
+
+No pretrained model weights are bundled in the repository. The deep backend
+downloads weights on first use (cached in `~/.cache/hotgaze/`). Model license
+audit is conducted in T0.3 and will be appended below.
+
+### Model audit (T0.3 — completed 2026-07-11)
+
+#### Saliency backends (deep backend candidates)
+
+##### 1. UNISAL — ✅ SELECTED as default deep backend
+
+| Field | Value |
+|-------|-------|
+| URL | https://github.com/rdroste/unisal |
+| Code license | Apache License 2.0 |
+| Weights license | Apache License 2.0 (weights are part of the repo, same license) |
+| Weights file 1 | `weights_best.pth` (14.7 MB) — trained on SALICON |
+| Weights file 2 | `weights_ft_mit1003.pth` (14.7 MB) — fine-tuned on MIT1003 |
+| Hosting | GitHub repo (`raw.githubusercontent.com`) — stable URL, not Google Drive |
+| SHA-256 (weights_best) | `4a9157411f1741d588b15670d15295e998805648b8b6348599fe447298338481` |
+| SHA-256 (weights_ft_mit1003) | `a6de8ea27d812cfc3fbc2b8cab59862a8e48aaf4d512e670468d3b6972a81262` |
+| Framework | PyTorch (native) |
+| Redistribution | ✅ YES — Apache 2.0 Section 4 permits reproduction + distribution |
+| **Final verdict** | **OK** — permissive license, stable URL, redistribution-allowed |
+
+##### 2. DeepGaze IIE — ❌ REJECTED (no license)
+
+| Field | Value |
+|-------|-------|
+| URL | https://github.com/matthias-k/DeepGaze |
+| Code license | **None** — no LICENSE file; `setup.py` license fields commented out; defaults to "all rights reserved" |
+| Weights license | None (same as code) |
+| Weights URL | GitHub Releases (`v1.0.0` tag) — stable URL |
+| Weights files | `deepgaze2e.pth` (~400 MB), `centerbias_mit1003.npy` (~8 MB) |
+| Framework | PyTorch (native) |
+| Redistribution | ❌ NO — no license grants redistribution rights |
+| **Final verdict** | **needs-author-contact** — contact matthias.kuemmerer@bethgelab.org; GitHub issue #15 (commercial use) unanswered since Oct 2023 |
+
+##### 3. MSI-Net — ✅ OK (fallback, TF → ONNX path)
+
+| Field | Value |
+|-------|-------|
+| URL | https://github.com/alexanderkroner/saliency |
+| Code license | MIT |
+| Weights license | MIT (HuggingFace model card confirms) |
+| Weights URL | https://huggingface.co/alexanderkroner/MSI-Net |
+| Framework | TensorFlow (original); foveacast-training provides PyTorch port + ONNX export |
+| Redistribution | ✅ YES — MIT permits use, copy, modify, merge, publish, distribute |
+| **Final verdict** | **OK** — MIT-licensed, but TF dependency adds complexity; eligible only via ONNX export per CLAUDE.md |
+
+#### Face detection candidates
+
+##### 1. YuNet — ✅ SELECTED
+
+| Field | Value |
+|-------|-------|
+| URL | https://github.com/opencv/opencv_zoo (models/face_detection_yunet) |
+| Code license | MIT |
+| Weights license | MIT |
+| Weights URL | https://huggingface.co/opencv-zoo/face-detection-yunet (227 KB ONNX) |
+| SHA-256 | `8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4` |
+| Integration | Native `cv2.FaceDetectorYN` API (OpenCV ≥ 4.5) |
+| Redistribution | ✅ YES — MIT-licensed |
+| **Final verdict** | **OK** — tiny (232 KB), native OpenCV API, MIT |
+
+##### 2. UltraFace — ✅ OK (fallback)
+
+| Field | Value |
+|-------|-------|
+| URL | https://github.com/Linzaer/Ultra-Light-Fast-Generic-Face-Detector-1MB |
+| Code license | MIT |
+| Weights license | MIT |
+| Weights URL | ONNX weights available (~1.2 MB) |
+| Integration | `cv2.dnn.readNetFromONNX` (standard OpenCV DNN) |
+| Redistribution | ✅ YES — MIT-licensed |
+| **Final verdict** | **OK** — lightweight, standard DNN integration |
+
+#### Exclusion notes
+
+- **RetinaFace / InsightFace / SCRFD**: Code MIT, but pretrained models carry **non-commercial** restriction explicitly in README → **REJECTED**
+- **DBFace**: No license specified → **REJECTED** (all rights reserved)
+- **BlazeFace**: Apache 2.0 but TFLite format → excluded (no TFLite in deps)
+
+#### Hosting plan
+
+- UNISAL weights will be re-hosted from our own GitHub Release with pinned SHA-256 checksums (required by CLAUDE.md — original hosting is not Google Drive, but we re-host to control checksumming and availability)
+- YuNet weights will be re-hosted from our own GitHub Release (232 KB, trivial)
+- Download-on-first-use, cached in `~/.cache/hotgaze/` with `HOTGAZE_CACHE` env override
+
+#### Default deep backend
+
+**UNISAL** — best quality among PyTorch-native models with permissive license (Apache 2.0) AND redistribution rights. PyTorch-native (no TF/ONNX complexity). Two weight variants available (SALICON-trained and MIT1003-fine-tuned).
+
+#### Vendored code
+
+| Source | Files | License | Commit | Notes |
+|--------|-------|---------|--------|-------|
+| https://github.com/rdroste/unisal | `_unisal/_model.py`, `_unisal/_mobilenet.py`, `_unisal/_cgru.py` | Apache 2.0 | HEAD (2026-07-12) | Inference-only subset; training/dataset code removed. `_model.py` modified to remove training methods and KwConfigClass; `_mobilenet.py` and `_cgru.py` are unmodified except for the license header.
+| https://github.com/rdroste/unisal | `mobilenet_v2.pth.tar` (14,205,652 B, SHA-256 `ecbe2b56…`) | Apache 2.0 | Bundled in UNISAL repo | ImageNet-pretrained MobileNetV2 backbone. Bundled in UNISAL under same Apache 2.0 license; no separate NOTICE in the upstream. Redistribution: ✅ per Apache 2.0.

hotgaze-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: hotgaze
+Version: 0.1.0
+Summary: Predict visual attention on UI screenshots — heatmap overlays and machine-readable attention scores
+Project-URL: Homepage, https://github.com/suryakosaraju/hotgaze
+Project-URL: Repository, https://github.com/suryakosaraju/hotgaze
+Author: Surya Kosaraju
+License: MIT
+License-File: LICENSE
+License-File: LICENSES-THIRD-PARTY.md
+Keywords: attention,eye-tracking,heatmap,saliency,ui,ux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: deep
+Requires-Dist: torch>=2.0; extra == 'deep'
+Provides-Extra: dev
+Requires-Dist: actionlint-py>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: scikit-image>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HotGaze ⏿
+
+[![CI](https://github.com/suryakosaraju/hotgaze/actions/workflows/ci.yml/badge.svg)](https://github.com/suryakosaraju/hotgaze/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/suryakosaraju/hotgaze/blob/main/pyproject.toml)
+
+Attention heatmaps for UI screenshots — with **numeric scores and A/B compare**, not just pretty pictures.
+
+Predict where users' eyes land on a design, get a machine-readable attention share for any region, and diff two variants to see which one wins and by how much. Local, offline, MIT-licensed.
+
+![Original design next to its HotGaze attention overlay — headline, CTA, and sidebar items glow hot](https://raw.githubusercontent.com/suryakosaraju/hotgaze/main/docs/demo.png)
+
+> **Status: v0.1 alpha.** The fast heuristic backend, region scoring, A/B compare, and deep UNISAL backend are shipping. Faces layer (YuNet) is available via `--layers faces`. API and CLI may change before v1.
+
+## Why this exists
+
+Every existing attention-prediction tool — paid ([HeatScope](https://heatscope.space), Attention Insight, EyeQuant) and free ([Foveacast](https://www.allaboutken.com/posts/20260503-foveacast/)) — stops at a colored overlay for a human to eyeball. That's fine for a designer squinting at a mockup. It's useless when you want to:
+
+- Compare two design variants and *quantify* which one draws more attention to the CTA.
+- Wire attention checks into CI ("your button just lost 23% of its attention").
+- Script or automate any part of the design-review loop.
+
+HotGaze outputs the picture too, but the picture isn't the point. The **numbers** are.
+
+## Install
+
+Not on PyPI yet (v0.1 is a working-directory install):
+
+```bash
+git clone https://github.com/suryakosaraju/hotgaze
+cd hotgaze
+pip install -e .
+```
+
+Python 3.10+. Runs on macOS and Linux. No cloud, no API keys, no telemetry.
+
+## Quickstart
+
+```bash
+# Generate an attention overlay
+hotgaze run screenshot.png -o overlay.png
+
+# Score a specific region — how much attention does the CTA get?
+hotgaze score screenshot.png --region cta:250,200,200,35 --json
+
+# Compare two variants — which one wins?
+hotgaze compare landing_a.png landing_b.png --region cta:250,200,200,35
+```
+
+## The differentiator: numbers, not just pictures
+
+**Score any region.** Attention share, peak value, rank — canonical JSON, deterministic on the same machine:
+
+```bash
+$ hotgaze score design.png --region cta:250,200,200,35 --json
+{
+  "schema": 1,
+  "regions": [
+    {"name": "cta", "share": 0.035, "peak_value": 0.769, "rank": 1}
+  ],
+  "focal_points": [...]
+}
+```
+
+**Compare two variants.** Per-region deltas, plus a 3×3 spatial grid showing where attention *moved*:
+
+```bash
+$ hotgaze compare landing_a.png landing_b.png --region cta:250,200,200,35 --json
+{
+  "compare": {
+    "per_region_deltas": [
+      {"name": "cta", "share_a": 0.035, "share_b": 0.022, "delta": -0.013}
+    ]
+  }
+}
+```
+
+Variant B lost 37% of the CTA's attention share. That's an actionable number, not "the heatmap looks about the same."
+
+## What's in the box
+
+- **CLI**: `hotgaze run`, `hotgaze score`, `hotgaze compare`, `hotgaze info`.
+- **Fast heuristic backend** (default): spectral-residual saliency + contrast + center bias + F-pattern reading prior. No downloads, works offline, sub-second on CPU.
+- **Deep saliency backend** (`--backend deep`): [UNISAL](https://github.com/rdroste/unisal) (Apache-2.0), CPU-only, deterministic per-machine. Install: `pip install hotgaze[deep]`. Weights download on first use (one-time, ~30 MB).
+- **Faces layer** (`--layers faces`): [YuNet](https://github.com/opencv/opencv_zoo) (MIT) face detection adds attention blobs over detected faces.
+- **Versioned JSON output**: schema v1 covers both score and compare modes so downstream tools don't break on new features.
+- **Deterministic**: same image + same config + same machine → byte-identical JSON.
+
+## Backends
+
+| Backend | Default | What it uses | Quality |
+|---------|---------|-------------|---------|
+| `fast` | ✅ | Spectral residual + contrast + center bias + gaze flow | Strong on flat UI screenshots; zero downloads |
+| `deep` | | UNISAL pretrained saliency model (PyTorch) | Better on natural images; on flat UIs the fast backend often matches or exceeds it — the domain gap is real. |
+
+`--backend deep` requires `pip install hotgaze[deep]` and a one-time weight download on first use. Both backends are fully offline after the initial fetch.
+
+## What HotGaze isn't
+
+- **Not real eye-tracking.** It's a prediction from computer-vision priors. Useful for early design review; not a substitute for a user study.
+- **Not a conversion oracle.** Attention share correlates with visibility, not with conversion — high attention on a bad CTA still doesn't sell.
+- **Not a designer GUI.** It's a scriptable tool for developers. A GUI/Figma plugin is roadmap, not v1.
+
+## Roadmap
+
+- **v0.2** — PyPI release, GitHub Action for attention regression testing on PR screenshots.
+- **v0.3+** — UI-tuned text/saliency models, Figma plugin, macOS wrapper, benchmarking against public saliency datasets.
+
+
+## License
+
+MIT. See [LICENSE](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSE).
+
+Third-party models and dependencies are recorded with their licenses and redistribution status in [LICENSES-THIRD-PARTY.md](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSES-THIRD-PARTY.md).
+
+## Credits
+
+Predictive saliency stands on decades of vision research. The deep backend builds on [UNISAL](https://github.com/rdroste/unisal) (Droste et al.). The fast backend implements [Hou & Zhang's spectral-residual approach (2007)](https://www.cv-foundation.org/openaccess/content_cvpr_2007/papers/Hou_Saliency_Detection_A_Spectral_Residual_Approach_CVPR_2007_paper.pdf). Face detection uses [YuNet](https://github.com/opencv/opencv_zoo).

hotgaze-0.1.0/README.md

@@ -0,0 +1,118 @@
+# HotGaze ⏿
+
+[![CI](https://github.com/suryakosaraju/hotgaze/actions/workflows/ci.yml/badge.svg)](https://github.com/suryakosaraju/hotgaze/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/suryakosaraju/hotgaze/blob/main/pyproject.toml)
+
+Attention heatmaps for UI screenshots — with **numeric scores and A/B compare**, not just pretty pictures.
+
+Predict where users' eyes land on a design, get a machine-readable attention share for any region, and diff two variants to see which one wins and by how much. Local, offline, MIT-licensed.
+
+![Original design next to its HotGaze attention overlay — headline, CTA, and sidebar items glow hot](https://raw.githubusercontent.com/suryakosaraju/hotgaze/main/docs/demo.png)
+
+> **Status: v0.1 alpha.** The fast heuristic backend, region scoring, A/B compare, and deep UNISAL backend are shipping. Faces layer (YuNet) is available via `--layers faces`. API and CLI may change before v1.
+
+## Why this exists
+
+Every existing attention-prediction tool — paid ([HeatScope](https://heatscope.space), Attention Insight, EyeQuant) and free ([Foveacast](https://www.allaboutken.com/posts/20260503-foveacast/)) — stops at a colored overlay for a human to eyeball. That's fine for a designer squinting at a mockup. It's useless when you want to:
+
+- Compare two design variants and *quantify* which one draws more attention to the CTA.
+- Wire attention checks into CI ("your button just lost 23% of its attention").
+- Script or automate any part of the design-review loop.
+
+HotGaze outputs the picture too, but the picture isn't the point. The **numbers** are.
+
+## Install
+
+Not on PyPI yet (v0.1 is a working-directory install):
+
+```bash
+git clone https://github.com/suryakosaraju/hotgaze
+cd hotgaze
+pip install -e .
+```
+
+Python 3.10+. Runs on macOS and Linux. No cloud, no API keys, no telemetry.
+
+## Quickstart
+
+```bash
+# Generate an attention overlay
+hotgaze run screenshot.png -o overlay.png
+
+# Score a specific region — how much attention does the CTA get?
+hotgaze score screenshot.png --region cta:250,200,200,35 --json
+
+# Compare two variants — which one wins?
+hotgaze compare landing_a.png landing_b.png --region cta:250,200,200,35
+```
+
+## The differentiator: numbers, not just pictures
+
+**Score any region.** Attention share, peak value, rank — canonical JSON, deterministic on the same machine:
+
+```bash
+$ hotgaze score design.png --region cta:250,200,200,35 --json
+{
+  "schema": 1,
+  "regions": [
+    {"name": "cta", "share": 0.035, "peak_value": 0.769, "rank": 1}
+  ],
+  "focal_points": [...]
+}
+```
+
+**Compare two variants.** Per-region deltas, plus a 3×3 spatial grid showing where attention *moved*:
+
+```bash
+$ hotgaze compare landing_a.png landing_b.png --region cta:250,200,200,35 --json
+{
+  "compare": {
+    "per_region_deltas": [
+      {"name": "cta", "share_a": 0.035, "share_b": 0.022, "delta": -0.013}
+    ]
+  }
+}
+```
+
+Variant B lost 37% of the CTA's attention share. That's an actionable number, not "the heatmap looks about the same."
+
+## What's in the box
+
+- **CLI**: `hotgaze run`, `hotgaze score`, `hotgaze compare`, `hotgaze info`.
+- **Fast heuristic backend** (default): spectral-residual saliency + contrast + center bias + F-pattern reading prior. No downloads, works offline, sub-second on CPU.
+- **Deep saliency backend** (`--backend deep`): [UNISAL](https://github.com/rdroste/unisal) (Apache-2.0), CPU-only, deterministic per-machine. Install: `pip install hotgaze[deep]`. Weights download on first use (one-time, ~30 MB).
+- **Faces layer** (`--layers faces`): [YuNet](https://github.com/opencv/opencv_zoo) (MIT) face detection adds attention blobs over detected faces.
+- **Versioned JSON output**: schema v1 covers both score and compare modes so downstream tools don't break on new features.
+- **Deterministic**: same image + same config + same machine → byte-identical JSON.
+
+## Backends
+
+| Backend | Default | What it uses | Quality |
+|---------|---------|-------------|---------|
+| `fast` | ✅ | Spectral residual + contrast + center bias + gaze flow | Strong on flat UI screenshots; zero downloads |
+| `deep` | | UNISAL pretrained saliency model (PyTorch) | Better on natural images; on flat UIs the fast backend often matches or exceeds it — the domain gap is real. |
+
+`--backend deep` requires `pip install hotgaze[deep]` and a one-time weight download on first use. Both backends are fully offline after the initial fetch.
+
+## What HotGaze isn't
+
+- **Not real eye-tracking.** It's a prediction from computer-vision priors. Useful for early design review; not a substitute for a user study.
+- **Not a conversion oracle.** Attention share correlates with visibility, not with conversion — high attention on a bad CTA still doesn't sell.
+- **Not a designer GUI.** It's a scriptable tool for developers. A GUI/Figma plugin is roadmap, not v1.
+
+## Roadmap
+
+- **v0.2** — PyPI release, GitHub Action for attention regression testing on PR screenshots.
+- **v0.3+** — UI-tuned text/saliency models, Figma plugin, macOS wrapper, benchmarking against public saliency datasets.
+
+
+## License
+
+MIT. See [LICENSE](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSE).
+
+Third-party models and dependencies are recorded with their licenses and redistribution status in [LICENSES-THIRD-PARTY.md](https://github.com/suryakosaraju/hotgaze/blob/main/LICENSES-THIRD-PARTY.md).
+
+## Credits
+
+Predictive saliency stands on decades of vision research. The deep backend builds on [UNISAL](https://github.com/rdroste/unisal) (Droste et al.). The fast backend implements [Hou & Zhang's spectral-residual approach (2007)](https://www.cv-foundation.org/openaccess/content_cvpr_2007/papers/Hou_Saliency_Detection_A_Spectral_Residual_Approach_CVPR_2007_paper.pdf). Face detection uses [YuNet](https://github.com/opencv/opencv_zoo).