Upload README.md with huggingface_hub

README.md

@@ -1,26 +1,96 @@
----
-tags:
-- ml-intern
----
+# ClashCR
 
-# stevenkhan/clashcr
+Real-time Clash Royale opponent card tracker for emulator gameplay (MuMu Player, BlueStacks).
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
+## Key Principle
+**Prefer "no detection / unknown" over a wrong card.** The tracker is only useful if it stops hallucinating.
 
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
+## Why the Old Approach Failed
+The previous whole-frame card classifier was the wrong visual task. In normal live gameplay, opponent card art and names are **never visible**. The only visible signals are:
+- Unit spawns on the arena
+- Spell/effect animations
+- Building placements
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+This rewrite detects **card-play events from spawn/effect evidence**, not by classifying random battlefield frames.
 
-## Usage
+## Architecture
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+```
+Emulator Capture (Win32 API / mss)
+    |
+    v
+Battle Gater (detect battle vs lobby, compute ROIs)
+    |
+    v
+Event Detector (temporal differencing, suppress persistent motion)
+    |
+    v
+Evidence Model (YOLO unit detector + heuristic spell detectors)
+    |
+    v
+Card Resolver (unit->card mapping, multi-unit rules, ambiguity->UNKNOWN)
+    |
+    v
+Elixir Tracker + Deck Tracker
+```
+
+## Setup
+
+```bash
+pip install -e .
+clashcr sync-cards --config config.yaml
+```
+
+If you have an Official Clash Royale API token, add it to `config.yaml` under `clash_royale_api_token`.
+
+## CLI Commands
+
+```bash
+# Sync card registry from APIs
+clashcr sync-cards --config config.yaml
+
+# Record battle footage
+clashcr record-battle --config config.yaml --output data/live-recordings/session-001 --seconds 180 --fps 8
 
-model_id = 'stevenkhan/clashcr'
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
+# Label a recording (edit labels.csv manually)
+clashcr label-recording --recording data/live-recordings/session-001
+
+# Train event detection model (placeholder)
+clashcr train-event-model --config config.yaml --data data/live-recordings
+
+# Evaluate predictions vs labels
+clashcr evaluate-recording --config config.yaml --recording data/live-recordings/session-heldout --labels data/live-recordings/session-heldout/labels.csv
+
+# Live tracking run
+clashcr run --config config.yaml --raw --debug-frame debug-frame.jpg --debug-dir debug-events
 ```
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+## Project Structure
+
+```
+clashcr/
+  core/
+    capture.py          # Emulator window capture
+    battle_gating.py    # Battle detection and ROI separation
+    event_detector.py   # Temporal event detection
+    recorder.py         # Evidence recording and labeling
+    evaluator.py        # Offline metrics evaluation
+  models/
+    evidence_model.py   # YOLO + spell heuristics
+    card_resolver.py    # Unit->card mapping with ambiguity handling
+  game/
+    elixir_tracker.py   # Wall-clock elixir estimation
+    deck_tracker.py     # Deck/cycle inference
+  utils/
+    card_registry.py    # Sync card list from RoyaleAPI + Official API
+  cli.py                # Entry point
+```
+
+## Verification
+See VERIFICATION_PLAN.md for the full validation protocol. No accuracy claims should be made without labeled recordings.
+
+## Research
+See RESEARCH_SUMMARY.md for evaluated projects, datasets, and APIs.
+
+## Rewrite Plan
+See REWRITE_PLAN.md for the detailed technical migration guide.