Update README.md

README.md

@@ -1,3 +1,166 @@
----
-license: mit
----
+---
+license: mit
+library_name: xgboost
+tags:
+  - tabular-regression
+  - ens
+  - ethereum
+  - web3
+  - domain-names
+  - price-prediction
+datasets:
+  - quantumly/ens-appraiser-data
+metrics:
+  - r_squared
+  - mape
+model-index:
+  - name: ENS Appraiser v0
+    results:
+      - task:
+          type: tabular-regression
+          name: ENS Domain Price Prediction
+        dataset:
+          name: ENS Appraiser Multi-source Training Data
+          type: quantumly/ens-appraiser-data
+        metrics:
+          - type: r_squared
+            value: TODO
+            name: R² (log USD)
+          - type: median_ape
+            value: TODO
+            name: Median APE
+          - type: rmse
+            value: TODO
+            name: RMSE (log USD)
+---
+
+# ENS Appraiser
+
+A gradient-boosted regression model that predicts the USD sale price of an
+ENS (`.eth`) domain name. This is the v0 baseline — handcrafted features +
+mpnet semantic embeddings + KNN comparable-sale aggregates.
+
+> ⚠️ Numeric values in the YAML frontmatter (`TODO`) and the **Evaluation**
+> table below should be filled in with the values from the training
+> notebook's `=== v0 SUMMARY ===` block. The notebook prints exact
+> R²/RMSE/MAPE for train/val/test — copy them here before merging.
+
+## Model Details
+
+- **Architecture**: XGBoost regressor on `log(sale_price_usd)`
+- **Features**: ~150 total
+  - 15 handcrafted (length, character composition, palindrome/repetition flags)
+  - 8 wordlist hits (Wikipedia, GeoNames, US firstnames, ISO 3166, stock tickers, SEC EDGAR, Wiktionary EN)
+  - ~45 grails club memberships (binary per club)
+  - 1 trademark conflict flag (active USPTO marks in Nice classes 9/35/36/38/41/42/45)
+  - 3 holder behavior (name age, registrant portfolio size, lifetime transfer count)
+  - 5 macro context (Fear & Greed, ETH TVL, ETH stablecoin mcap, ETH DEX volume, NFT marketplace fees)
+  - 64 PCA-reduced mpnet embedding dims (from `sentence-transformers/all-mpnet-base-v2`)
+  - 8 KNN comparable-sale aggregates (count, mean/median/p90 log price of nearest neighbors with prior sales)
+- **Training data**: ENS secondary sales, Jan 2022 — May 2024 (~384k events)
+- **Validation**: temporal split (80/10/10 by sale date, no shuffle to prevent KNN-comp leakage)
+
+## Evaluation
+
+| Split | R² (log USD) | RMSE (log USD) | Median APE |
+|---|---|---|---|
+| Train | TODO | TODO | TODO |
+| Val   | TODO | TODO | TODO |
+| Test  | TODO | TODO | TODO |
+
+## Intended Use
+
+This model predicts sale prices for ENS `.eth` domain names. It's intended
+for **research and analytics**, not for live trading or as a price oracle.
+
+**Use cases it handles well:**
+
+- Bulk valuation of mid-tier names ($50–$5,000 range)
+- Identifying obviously over- or under-priced listings
+- Portfolio-level mark-to-market for ENS holdings
+- Sanity-checking listing prices
+
+**Use cases where it's weak:**
+
+- Celebrity/brand-name premium tail ($50k+ sales) — the model lacks fame data
+- Future names not in training distribution (post-May 2024)
+- Names registered through pathways the subgraph doesn't index
+- Blur-marketplace sales — Alchemy `getNFTSales` v2 doesn't index Blur for ENS,
+  so the training data has a marketplace coverage gap
+
+## Limitations
+
+- **Sales coverage limitation**: Training data covers Jan 2022 — May 2024 only.
+  Alchemy's `getNFTSales` v2 endpoint truncates ENS coverage at block 19768978
+  (~May 2024) and doesn't index Blur sales.
+- **Celebrity tail**: Names with significant out-of-band brand value
+  (`coinbase.eth`, `vault.eth`) will be systematically underpriced because
+  the model lacks features for "is this a famous person/brand."
+- **Out-of-distribution labels**: Pure-digit labels (`0001`), punycode/emoji,
+  and l33tspeak get less benefit from mpnet embeddings since they were
+  out-of-distribution for the pretrained model.
+- **Time drift**: ENS market regime shifts in 2024-2025 are not captured.
+  Predictions for current names will lag those regime shifts.
+
+## How to Use
+
+```python
+from huggingface_hub import hf_hub_download
+import xgboost as xgb
+import pickle
+
+# Download model artifacts
+model_path = hf_hub_download(
+    repo_id="quantumly/ens-appraiser",
+    filename="v0_appraiser_xgb.json",
+)
+pca_path = hf_hub_download(
+    repo_id="quantumly/ens-appraiser",
+    filename="v0_pca_mpnet.pkl",
+)
+
+# Load
+booster = xgb.Booster()
+booster.load_model(model_path)
+with open(pca_path, "rb") as f:
+    pca = pickle.load(f)
+
+# To make predictions you'll also need:
+# 1. The mpnet embedding for the label (run sentence-transformers all-mpnet-base-v2)
+# 2. The handcrafted features, wordlist lookups, club memberships, trademark check
+# 3. Macro context for the prediction date (ETH price, Fear & Greed, etc.)
+# 4. KNN comp lookup against the FAISS index from the dataset repo
+#
+# See the inference notebook in the dataset repo for the full pipeline.
+```
+
+## Training Data
+
+Built from the [`quantumly/ens-appraiser-data`](https://huggingface.co/datasets/quantumly/ens-appraiser-data)
+dataset, which assembles:
+
+- ENS on-chain registrations, renewals, transfers (The Graph subgraph)
+- ENS secondary sales (Alchemy `getNFTSales`)
+- CoinGecko hourly OHLC for label denomination
+- Discourse forums for governance signal
+- DefiLlama for macro signals (TVL, stablecoin mcap, DEX volume, NFT marketplace fees)
+- USPTO trademark registry for brand-conflict flags
+- Grails club memberships
+- Wiktionary, Wikipedia, GeoNames, US Census, SEC EDGAR for wordlist hits
+- `sentence-transformers/all-mpnet-base-v2` for semantic embeddings
+
+## Citation
+
+```bibtex
+@misc{ens_appraiser_2026,
+  author = {Drobnič, Nejc},
+  title  = {ENS Appraiser},
+  year   = {2026},
+  publisher = {Hugging Face},
+  url    = {https://huggingface.co/quantumly/ens-appraiser}
+}
+```
+
+## Contact
+
+nejc@nejc.dev