Add repo card explaining Stage-1 interpreter/router

README.md

@@ -0,0 +1,95 @@
+---
+base_model: Qwen/Qwen2.5-0.5B-Instruct
+library_name: transformers
+pipeline_tag: text-generation
+license: other
+language:
+  - en
+tags:
+  - color-grading
+  - lut
+  - instruction-following
+  - routing
+  - refusal
+  - intent-classification
+  - qwen2
+---
+
+# LUT-SLM — Stage-1 Interpreter / Router (Qwen2.5-0.5B, full fine-tune)
+
+The **Stage-1 interpreter** for the LUT-SLM project: a small **text-only** model (full fine-tune of
+`Qwen/Qwen2.5-0.5B-Instruct`) that reads a user's free-text photo-editing request and decides **how to
+handle it** before any LUT is generated. It emits an `attribute_spec_text` plus a **route**:
+
+- **`grade`** — a global color LUT can satisfy this → hand off to the Stage-2 generator.
+- **`clarify`** — the request is underspecified / out of gamut → ask a clarifying question.
+- **`refuse`** — a single global LUT physically cannot do this (`out_of_scope`) or the ask is out of
+  gamut (`out_of_gamut`) → refuse instead of fabricating a wrong grade.
+
+It is the safety gatekeeper of the two-stage architecture: *never silently grade a request that should
+be refused or clarified.* The Stage-2 generator adapters live in
+**[`ericrcwu/LUT_SLM_sft_adapters`](https://huggingface.co/ericrcwu/LUT_SLM_sft_adapters)**; the
+training corpus + teacher caches are in
+**[`ericrcwu/LUT_SLM_interpreter_cache`](https://huggingface.co/datasets/ericrcwu/LUT_SLM_interpreter_cache)**;
+the source data is **[`ericrcwu/LUT_SLM`](https://huggingface.co/datasets/ericrcwu/LUT_SLM)**.
+
+## Subfolders
+
+| Subfolder | What it is |
+|---|---|
+| `interp_full_smokefull/` | **The router.** Full-run interpreter used by the deploy path (`deploy/modal_app.py`, `INTERPRETER_SUBDIR = "interp_full_smokefull"`). |
+| `interp_intensity/` | Intensity-fix experiment variant (re-captioned to surface magnitude buckets). Kept for comparison; **not** the deployed model. |
+
+Each folder is a full model (`model.safetensors` ≈ 0.99 GB, `config.json`, tokenizer, chat template) —
+these are **full fine-tunes, not adapters**. Architecture: Qwen2, hidden size 896, 24 layers, 14 heads
+(2 KV heads), vocab 151,936, bf16, tied embeddings.
+
+## Results (from `docs/interpreter_results.md`)
+
+**✅ Routing is production-ready** (full run, 2761 LUTs, n=684 holdout):
+
+| metric | value |
+|---|---|
+| route accuracy (3-way) | **0.884** (CI 0.858–0.906) |
+| refuse recall / refuse-kind accuracy | **1.0 / 1.0** |
+| clarify recall | **1.0** |
+| grade recall | 0.868 |
+| over-refusal rate | 0.132 |
+| parse-ok rate | 0.886 |
+
+**❌ Grade *magnitude* is not learnable from vague text.** The exact-magnitude score plateaued at
+`attribute_f1 ≈ 0.11` and did not improve with 5× data or an intensity-aware caption fix. Diagnosis:
+**task underdetermination** — "make it warmer" doesn't encode *how much*, and the same phrasing maps to
+different measured magnitudes across LUTs, so `(text → magnitude)` supervision is contradictory. The
+model reliably learns **direction** (words carry it, dir-F1 ≈ 0.47) but not **magnitude** (words don't).
+
+**Decision: ship as a ROUTER only.** For `grade`, forward the **raw user text** to the one-stage
+generator (which learns magnitude end-to-end) rather than the interpreter's magnitude-free spec.
+
+## How to load
+
+```python
+from huggingface_hub import snapshot_download
+from transformers import AutoModelForCausalLM, AutoTokenizer
+d = snapshot_download("ericrcwu/LUT_SLM_interpreter", allow_patterns=["interp_full_smokefull/*"])
+tok = AutoTokenizer.from_pretrained(f"{d}/interp_full_smokefull")
+model = AutoModelForCausalLM.from_pretrained(f"{d}/interp_full_smokefull")
+# Build the prompt with interpreter.example.build_prompt_ids, then parse the generated text with
+# interpreter.comparator.parse -> {route, attribute_spec}. (Helpers live in the source repo.)
+```
+
+## Intended use & limitations
+
+- **Use it as a router / gatekeeper** for grade / clarify / refuse. Optionally use its predicted
+  *direction* as a soft hint to the generator (~0.5 reliable).
+- **Do not** rely on it for grade magnitude — that path is deliberately handed to the Stage-2
+  generator. Reopen the grade path only if the input distribution changes to carry explicit intensity
+  (e.g. a guided UI).
+
+## Licensing & provenance
+
+`license: other`. The base model carries the Apache-2.0 Qwen2.5-0.5B license; this fine-tune is derived
+from the mixed-provenance LUT-SLM corpus (teacher-LLM captions of real LUTs, some from
+personal-use/non-redistribution sources — see the
+[`LUT_SLM`](https://huggingface.co/datasets/ericrcwu/LUT_SLM) card). Research use; verify source terms
+before redistribution or commercial use.