First commit

CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+All commands must be run from the project root using the local venv:
+
+```bash
+# End-to-end identification (the main entry point)
+.venv/bin/python identify.py <image_path>
+
+# Train the model
+.venv/bin/python -m src.models.train --epochs 50 --batch_size 64 --lr 1e-4
+
+# Run inference only (no registry lookup)
+.venv/bin/python src/models/inference.py <image_path>
+
+# Generate/regenerate the fixed validation set (seed=42, 1000 samples, white bg)
+.venv/bin/python -m src.data.generate_val_set
+
+# Generate/regenerate the fixed augmented test set (seed=99, 500 samples)
+.venv/bin/python -m src.data.generate_aug_test_set
+
+# Generate a single sample image for visual inspection
+.venv/bin/python src/data/high_fidelity_generator.py
+
+# Lint
+.venv/bin/ruff check src/
+
+# Type check
+.venv/bin/mypy src/
+```
+
+The package is installed in editable mode (`pip install -e .`); imports use `src.*` paths.
+
+**Important:** DataLoader workers use `multiprocessing`, so training must be invoked as a module (`python -m src.models.train`), not as a script piped via stdin — Python cannot resolve the worker `main_path` in that case.
+
+## Architecture
+
+The pipeline has five stages:
+
+```
+Image → Detector → Inference → Resolver → Registry
+                  (cropped)   (logits)   (PIDs)     (SQLite)
+```
+
+### 1. Detection (`src/utils/detector.py`)
+
+`SpindaDetector.detect_and_crop()` returns a **128×128 BGR** image, or `None`.
+
+Two-tier strategy, tried in order:
+- **Tier 1 (screenshots/sprites):** HSV-filter red pixels → find individual spot blobs → cluster to 4 spots → derive crop from cluster centroid + `_SPOT_CROP_RATIO=5.5` (= 128 / 24.5 px span) with a `_SPOT_CENTER_OFFSET=0.056` downward shift so the spot centroid lands at 44.4 % from the top of the crop (matching the training canvas).
+- **Tier 2 (real photos, spots merged):** Find the full Spinda body blob; score = `circularity + 0.2·log(area/min_area) − 0.1·|aspect − 1.12|`; crop the face (top 43/58 of body height) using blob width as scale reference.
+
+### 2. Model (`src/models/regression_model.py`)
+
+ResNet-18 backbone with the final FC replaced by `Linear(512, 8·16)`. Forward pass returns **(B, 8, 16)** — treating each of the 8 coordinates as a 16-class classification problem. Trained with `CrossEntropyLoss` on `view(-1, 16)` vs `view(-1)` targets; predictions use `argmax(dim=2)`.
+
+### 3. Training (`src/models/train.py`)
+
+- `SpindaDataset` (200 k virtual samples/epoch): generates a fresh random 32-bit PID per `__getitem__`, renders the sprite with a random background colour, then applies the full augmentation pipeline.
+- `SpindaEvalDataset`: loads pre-generated images from disk (post-augmentation, pre-normalisation) and applies only the normalise step. Used for both `data/val/` (clean, seed=42) and `data/aug_test/` (augmented, seed=99).
+- `_worker_init_fn` re-seeds Python `random` and NumPy per worker so forked workers generate distinct PIDs.
+- Early stopping: patience = 10 epochs on clean-val exact-match rate.
+- Best model checkpoint: `models/best_spinda_model.pth`.
+
+### 4. PID Encoding (domain invariant — must not be changed)
+
+The 8 model outputs map directly to hex nibbles of the 32-bit PID via the **ProfessorRex** convention:
+
+| Coord index | Nibble | Spot | Notes |
+|-------------|--------|------|-------|
+| 0 (TL_x) | `pid[-1]` | TL | no pixel offset |
+| 1 (TL_y) | `pid[-2]` | TL | |
+| 2 (TR_x) | `pid[-3]` | TR | +24 px |
+| 3 (TR_y) | `pid[-4]` | TR | +1 px |
+| 4 (BL_x) | `pid[3]`  | BL | +6 px |
+| 5 (BL_y) | `pid[2]`  | BL | +18 px |
+| 6 (BR_x) | `pid[1]`  | BR | +18 px |
+| 7 (BR_y) | `pid[0]`  | BR | +19 px |
+
+`SpindaResolver.coordinates_to_pid()` reconstructs each byte as `(Y << 4) | X`; BDSP reverses the byte order.
+
+### 5. Registry (`src/registry/database.py`)
+
+SQLite at `data/spinda_registry.db`. Schema: `(fingerprint TEXT, pid_hex TEXT, UNIQUE)` with an index on `fingerprint`. `SpindaRegistry.add_entry()` is idempotent (ignores `IntegrityError`).
+
+## Data layout
+
+```
+data/
+  val/             # 1000 fixed clean sprites, white bg (seed=42) — stable benchmark
+    metadata.json
+    sample_NNNN.png
+  aug_test/        # 500 fixed augmented images (seed=99) — domain-adaptation tracker
+    metadata.json
+    sample_NNNN.png
+  spinda_registry.db
+
+assets/            # Sprite assets used by the renderer
+  Spinda_Base_Top.png   # 52×43 face layer
+  Spinda_Head.png       # colourisation source for spots
+  Spot_{TL,TR,BL,BR}.png
+
+models/
+  best_spinda_model.pth
+```
+
+`metadata.json` format: `[{"img_path": "...", "pid_hex": "...", "target": [int×8]}, ...]`
+
+## Key invariants
+
+- **Visual collisions:** ~1.3 % of fingerprints are shared by multiple PIDs (many-to-one mapping). `SpindaRegistry` stores `(fingerprint, pid_hex)` pairs with a unique constraint so `lookup_by_fingerprint` can return *all* matching PIDs — this is intentional, not a bug.
+
+- The **validation set** uses white backgrounds (no augmentation baked in) to give a stable epoch-comparable baseline. Do not add augmentation to `generate_val_set.py`.
+- The **augmented test set** is pre-generated and fixed. Regenerating it changes the baseline; do so intentionally.
+- The crop output size is always **128×128** regardless of tier. The model transform chain also resizes to 128×128, so the inference path is robust to re-size.
+- `generate_high_fidelity_spinda()` always takes `bg_color` as a `(R, G, B)` tuple in PIL order (not BGR).