Update README.md

README.md

@@ -1,4 +1,3 @@
-
 ---
 license: gemma
 pipeline_tag: text-generation
@@ -47,6 +46,21 @@ This repository contains **only the LoRA adapter**, not the full model.
 Loading it will automatically download the base model (`unsloth/gemma-4-E4B-it`) and apply the adapter in 4-bit.
 
 ```python
+
+# %% [Install]
+%%capture
+import os, re
+# Install everything needed for the T4 Colab environment
+!pip install sentencepiece protobuf "datasets==4.3.0" "huggingface_hub>=0.34.0" hf_transfer
+!pip install --no-deps unsloth_zoo bitsandbytes accelerate xformers peft trl triton unsloth
+!pip install --no-deps --upgrade "torchao>=0.16.0"
+!pip install --no-deps transformers==5.5.0 "tokenizers>=0.22.0,<=0.23.0"
+!pip install torchcodec
+import torch
+torch._dynamo.config.recompile_limit = 64
+
+#------------
+
 from unsloth import FastModel
 
 model, tokenizer = FastModel.from_pretrained(
@@ -86,6 +100,52 @@ print(predict_hs_code("Men's cotton knitted T-shirt"))
 
 ---
 
+## 🔍 Raw model output (debugging)
+
+If you want to see exactly what the model generated (including the rates it predicted) without the lookup table, use the raw‑output function below.  
+**Do not** use these rates in production – they are only for debugging or confidence evaluation.
+
+```python
+def predict_hs_code_raw(description: str, max_new_tokens=100) -> dict:
+    system_prompt = (
+        "You are a customs compliance AI. Classify the product description to its "
+        "correct 8-digit HS code and output the corresponding trade rates (Customs Duty, "
+        "Special Tax, VAT, Excise Tax) and unit."
+    )
+    messages = [
+        {"role": "system", "content": [{"type": "text", "text": system_prompt}]},
+        {"role": "user",   "content": [{"type": "text", "text": f"Description: {description}"}]},
+    ]
+    inputs = tokenizer.apply_chat_template(
+        messages, add_generation_prompt=True, tokenize=True,
+        return_dict=True, return_tensors="pt",
+    ).to("cuda")
+
+    out = model.generate(**inputs, max_new_tokens=max_new_tokens, use_cache=True, do_sample=False)
+    raw_text = tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+
+    def extract(pattern, text):
+        m = re.search(pattern, text)
+        return m.group(1).strip() if m else None
+
+    return {
+        "hs_code":   extract(r"HS Code:\s*([0-9.]+)", raw_text),
+        "unit":      extract(r"Unit:\s*(.*)", raw_text),
+        "cd_rate":   extract(r"Customs Duty:\s*([\d.]+)%?", raw_text),
+        "st_rate":   extract(r"Special Tax:\s*([\d.]+)%?", raw_text),
+        "vat_rate":  extract(r"VAT:\s*([\d.]+)%?", raw_text),
+        "et_rate":   extract(r"Excise Tax:\s*([\d.]+)%?", raw_text),
+        "raw_output": raw_text
+    }
+
+# Example
+raw = predict_hs_code_raw("Men's cotton knitted T-shirt")
+print(raw["raw_output"])
+print(raw["hs_code"])   # model’s guess
+```
+
+---
+
 ## 🧠 Training details
 
 - **Base model**: `unsloth/gemma-4-E4B-it` (4‑bit QLoRA)
@@ -154,14 +214,23 @@ Then use with Ollama (see [`Modelfile` example](https://ollama.com) – set temp
 
 | Description | Predicted HS Code | Unit | CD | ST | VAT | ET |
 |-------------|-------------------|------|----|----|-----|----|
-| Toyota Hilux pickup, diesel 2.8L | 8704 | u | 35% | 50% | 10% | 0% |
-| iPhone 15 Pro Max 256GB | 8517 | u | 0% | 0% | 10% | 0% |
-| Heineken beer 330ml can | 2203 | l | 35% | 30% | 10% | 0% |
+| Toyota Hilux pickup, diesel 2.8L | 87042110 | UNIT | 35% | 50% | 10% | 0% |
+| iPhone 15 Pro Max 256GB | 85171200 | UNIT | 0% | 0% | 10% | 0% |
+| Heineken beer 330ml can | 22030010 | LTR | 35% | 30% | 10% | 0% |
 
 *(Rates from lookup table – not generated by the model.)*
 
 ---
 
+## ⚠️ Limitations
+
+- The model may output incorrect HS codes for ambiguous, misspelled, or region‑specific descriptions.
+- It was trained on a fixed set of Cambodian HS codes; revisions after the training data cutoff are not covered.
+- Duty rates can become outdated – always cross‑check with the latest official tariff schedule.
+- The model is a classifier, **not** a legal authority. For binding decisions, consult a customs professional.
+
+---
+
 ## 📝 License
 
 This model is a derivative of **Gemma‑4‑E4B‑it** and is subject to the [Gemma license](https://ai.google.dev/gemma/terms).  
@@ -176,5 +245,21 @@ The HS‑code dataset and lookup table are the property of their respective owne
 
 ---
 
+## 📚 Citation
+
+If you use this model, please cite:
+
+```bibtex
+@misc{gemma4-hscode-classifier,
+  author = {Sothay},
+  title = {Gemma‑4 HS Code Classifier (Cambodia Customs)},
+  year = 2025,
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/Sothay/gemma4-hscode-classifier}}
+}
+```
+
+---
+
 **Author**: [Sothay](https://huggingface.co/Sothay)  
-**Model card version**: 1.1  
+**Model card version**: 1.2