Update README.md

README.md

@@ -1,3 +1,163 @@
----
-license: mit
----
+---
+license: apache-2.0
+base_model: Qwen/Qwen3-4B
+library_name: transformers
+tags:
+  - qwen3
+  - lora
+  - fine-tuned
+  - chain-of-thought
+  - structured-output
+  - json
+  - reasoning
+  - pos
+  - order-parsing
+pipeline_tag: text-generation
+language:
+  - en
+---
+
+# STRM-4B-v1: Stateful Reasoning Model
+
+A LoRA fine-tune of [Qwen/Qwen3-4B](https://huggingface.co/Qwen/Qwen3-4B) trained on distilled chain-of-thought data for parsing unstructured, spoken-language input into structured JSON.
+
+The model maintains running state while processing sequential instructions -- handling corrections ("scratch that"), cancellations ("actually nevermind"), quantity changes ("bump that to 3"), and modifier adjustments in a single forward pass.
+
+**~94% exact-match accuracy** averaged across evaluation domains.
+
+## Quick Start
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_id = "AryanNsc/strm-4b-v1"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="auto", device_map="auto")
+
+messages = [
+    {"role": "system", "content": "You are an expert POS agent. Parse the order step by step, then output JSON."},
+    {"role": "user", "content": "uh can I get a venti latte with oat milk and a blueberry muffin actually scratch that muffin make it an avocado toast"},
+]
+
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True, enable_thinking=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+output = model.generate(**inputs, max_new_tokens=2048, temperature=0.6, do_sample=True)
+print(tokenizer.decode(output[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
+```
+
+### Expected Output
+
+The model reasons inside `<think>` tags, then outputs structured JSON:
+
+```
+<think>
+Processing the order step by step:
+
+1. "venti latte with oat milk" -> Latte, Venti, Oat Milk
+   - Base: $4.50 + Venti: $1.00 + Oat Milk: $0.80 = $6.30
+
+2. "a blueberry muffin" -> Blueberry Muffin
+   - $3.75
+
+3. "actually scratch that muffin" -> Cancel the Blueberry Muffin
+
+4. "make it an avocado toast" -> Avocado Toast
+   - $7.00
+
+Running total: $6.30 + $7.00 = $13.30
+</think>
+{"items": [{"name": "Latte", "size": "Venti", "quantity": 1, "modifiers": ["Oat Milk"]}, {"name": "Avocado Toast", "size": null, "quantity": 1, "modifiers": []}], "total_price": 13.30}
+```
+
+## Intended Use
+
+STRM is designed for tasks that require **stateful sequential reasoning** -- processing a stream of instructions where later instructions modify earlier state. Primary use cases:
+
+- **Point-of-sale order parsing** -- spoken coffee shop, restaurant, or retail orders with corrections and modifications
+- **Grocery checkout / inventory** -- item additions, removals, quantity changes with running totals
+- **Banking transactions** -- sequential operations with balance tracking
+- **Bill splitting** -- multi-party calculations with adjustments
+- **Any domain** where input arrives sequentially and includes corrections to prior state
+
+## How It Works
+
+The model is trained with **distilled thinking** -- each training example includes explicit step-by-step reasoning inside `<think>` tags before the final JSON output. This teaches the model to:
+
+1. **Parse sequentially** -- process input phrase by phrase, not all at once
+2. **Track mutable state** -- maintain a running list of items/entities that gets updated with each action
+3. **Handle corrections** -- "scratch that", "remove that", "actually nevermind" modify tracked state rather than restarting
+4. **Show arithmetic** -- every price calculation is written out step by step, reducing computation errors
+5. **Output valid JSON** -- clean structured output after reasoning is complete
+
+Training data spans multiple domains with weighted sampling, so the model learns the general skill of stateful reasoning rather than memorizing domain-specific patterns.
+
+## Training Details
+
+| Parameter | Value |
+|-----------|-------|
+| Base model | [Qwen/Qwen3-4B](https://huggingface.co/Qwen/Qwen3-4B) |
+| Method | LoRA |
+| LoRA rank (r) | 64 |
+| LoRA alpha | 64 |
+| LoRA dropout | 0.0 |
+| Target modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Quantization | 4-bit NF4 (training only; weights are merged to 16-bit) |
+| Max sequence length | 4096 |
+| Learning rate | 2e-4 |
+| LR scheduler | Cosine with 5% warmup |
+| Weight decay | 0.01 |
+| Epochs | 3 |
+| Per-device batch size | 2 |
+| Gradient accumulation | 4 (effective batch size: 8) |
+| Precision | bf16 |
+| Seed | 42 |
+
+### Training Data
+
+The model was trained on multi-domain distilled chain-of-thought data. Each example consists of a system prompt, a user input, and an assistant response containing `<think>...</think>` reasoning followed by structured JSON. Domains include coffee shop orders, restaurant orders, grocery checkout, banking, inventory, bill splitting, recipe scaling, scheduling, budget tracking, and unit conversion -- with coffee-domain examples upsampled for the primary use case.
+
+## Evaluation
+
+Benchmarked on held-out labeled data across difficulty tiers:
+
+| Difficulty | Description |
+|------------|-------------|
+| Easy | 1-2 items, no corrections |
+| Medium | 2-3 items, some modifiers |
+| Hard | Multiple items with cancellations or quantity bumps |
+| Nightmare | 4+ items with mixed corrections, modifier removals, and re-additions |
+
+The model achieves **~94% exact-match accuracy** averaged across domains, where exact match requires both the item list (names, sizes, quantities, modifiers) and total price to be completely correct.
+
+### Metrics Reported
+
+- **Exact match** -- items + price both fully correct
+- **Items match** -- all items correct regardless of price
+- **Price match** -- total within $0.01 tolerance
+- **Per-field** -- names, sizes, quantities, modifiers evaluated independently
+
+## Usage Tips
+
+- **Use `enable_thinking=True`** in `apply_chat_template` -- the model was trained to reason inside `<think>` tags before outputting JSON
+- **Temperature 0.6** works well for most inputs; use **temperature 0** (greedy) for maximum consistency
+- **Max tokens 2048** is sufficient for most orders; nightmare-level inputs with 5+ items may need more
+- The JSON output appears **after** the `</think>` closing tag -- parse everything after that delimiter
+- The model handles filler words (uh, um, like, literally) natively -- no need to preprocess
+
+## Limitations
+
+- Trained primarily on English-language input
+- Price arithmetic can occasionally drift on very long orders (6+ items with many modifiers)
+- The model expects a system prompt describing the menu/domain; without it, output format may be inconsistent
+- Not designed for multi-turn conversation -- each inference is a single order
+
+## Training Code
+
+The full training and evaluation code is open source:
+
+[github.com/Guney-olu/strm-model](https://github.com/Guney-olu/strm-model)
+
+## License
+
+Apache 2.0