README.md

---
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.