Add README with run instructions

README.md

@@ -0,0 +1,80 @@
+# NeuroGolf Solver
+
+Solves ARC-AGI tasks by building minimal ONNX networks.
+
+## Current Results
+- **127/400** tasks solved on CPU with 15s budget per task
+- Expected **~140+** with 30s budget on faster hardware
+
+## How to Run
+
+### 1. Clone & setup
+```bash
+git clone https://huggingface.co/rogermt/neurogolf-solver
+cd neurogolf-solver
+pip install numpy onnx onnxruntime
+git clone --depth 1 https://github.com/fchollet/ARC-AGI.git
+```
+
+### 2. Run solver
+```bash
+# Default (30s conv budget per task)
+python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 30
+
+# Faster but fewer tasks
+python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 15
+
+# More time = more tasks solved (tries larger conv kernels)
+python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 60
+```
+
+### 3. On Kaggle (if task JSONs are in competition format)
+```bash
+python neurogolf_solver.py --data_dir /kaggle/input/competitions/neurogolf-2026/ --output_dir submission --kaggle --conv_budget 30
+```
+
+### 4. Create submission zip
+```python
+import zipfile, os
+with zipfile.ZipFile('submission.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
+    for f in sorted(os.listdir('submission')):
+        if f.endswith('.onnx'):
+            zf.write(os.path.join('submission', f), f)
+```
+
+## Architecture
+
+Each ONNX model follows one of these patterns:
+
+1. **Conv solver** (most tasks): `Slice[1,10,H,W] -> Conv2d -> ArgMax -> OneHot -> Pad[1,10,30,30]`
+   - Learns optimal conv weights via least-squares on one-hot encoded patches
+   - Tries kernel sizes 1,3,5,...,29 and picks smallest that fits perfectly
+   - Also tries with bias term for better boundary handling
+
+2. **Analytical solvers** (fast, tiny models):
+   - `identity`: Identity op
+   - `color_map`: 1x1 conv (channel permutation)
+   - `transpose`: Transpose dims 2,3
+   - `flip`: GatherElements with reversed indices
+   - `rotate`: GatherElements with rotated indices
+   - `tile`: Slice -> Tile -> Pad
+   - `upscale`: GatherElements with repeated indices
+   - `concat`: GatherElements with block-transformed indices
+   - `spatial_gather`: GatherElements with per-pixel source mapping
+   - `constant`: Multiply by 0, add constant
+
+## Format
+- Input: `[1, 10, 30, 30]` float32 (one-hot encoded grid, padded to 30x30)
+- Output: `[1, 10, 30, 30]` float32 (one-hot encoded grid)
+- Scoring: `(output > 0.0).astype(float)` must match expected one-hot
+- ONNX opset 10, IR version 10
+
+## Key Insight
+The critical trick is **Slice -> Conv -> ArgMax -> OneHot -> Pad**:
+- Slice extracts the actual grid from the 30x30 padded input (avoiding color-0 boundary issues)
+- Conv applies the learned transformation with zero-padding
+- ArgMax finds the winning color channel
+- OneHot converts back to clean one-hot (eliminates numerical precision issues)
+- Pad restores to 30x30
+
+Without ArgMax+OneHot, slight numerical noise from the conv causes validation failures.