Update README.md

README.md

@@ -1,6 +1,5 @@
 ---
 license: apache-2.0
-
 tags:
   - image-classification
   - multi-label-classification
@@ -49,11 +48,45 @@ backbone fine-tuned end-to-end with a single linear projection head.
 
 ## Usage
 
-### Web UI
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+Or manually:
+
+```bash
+pip install torch torchvision safetensors Pillow requests \
+            python-multipart fastapi uvicorn jinja2 aiofiles
+```
+
+### 2. Download model files
+
+```bash
+huggingface-cli download lodestones/taggerine \
+    tagger_proto.safetensors \
+    tagger_vocab_with_categories_and_alias_updated.json \
+    tagger_ui_server.py \
+    inference_tagger_standalone.py \
+    --local-dir .
+```
+
+> **Note:** `tagger_proto.safetensors` is ~5.3 GB. Make sure you have enough disk space.
+
+### 3. Download the `tagger_ui/` templates folder
+
+The server requires the `tagger_ui/templates/` directory to be present alongside `tagger_ui_server.py`:
 
 ```bash
-pip install fastapi uvicorn jinja2 aiofiles
+huggingface-cli download lodestones/taggerine \
+    --include "tagger_ui/**" \
+    --local-dir .
+```
 
+### 4. Run the Web UI
+
+```bash
 python tagger_ui_server.py \
     --checkpoint tagger_proto.safetensors \
     --vocab tagger_vocab_with_categories_and_alias_updated.json \
@@ -61,14 +94,37 @@ python tagger_ui_server.py \
 # → open http://localhost:7860
 ```
 
+**CPU-only machine?** Add `--device cpu` (inference will be slower):
+
+```bash
+python tagger_ui_server.py \
+    --checkpoint tagger_proto.safetensors \
+    --vocab tagger_vocab_with_categories_and_alias_updated.json \
+    --device cpu \
+    --port 7860
+```
+
+### Standalone CLI inference (no server)
+
+```bash
+python inference_tagger_standalone.py \
+    --checkpoint tagger_proto.safetensors \
+    --vocab tagger_vocab_with_categories_and_alias_updated.json \
+    --images photo.jpg \
+    --topk 30
+```
+
 ## Files
 
 | File | Description |
 |---|---|
-| `*.safetensors` | Model weights (bfloat16) |
-| `tagger_vocab_with_categories.json` | `{"idx2tag": [...]}` — 74 625 tag strings ordered by training frequency |
-| `inference_tagger_standalone.py` | Self-contained inference script (no `transformers` dep) |
+| `tagger_proto.safetensors` | Model weights (bfloat16) |
+| `tagger_vocab_with_categories_and_alias_updated.json` | `{"idx2tag": [...], "tag2category": {...}}` — 74 625 tags with category metadata |
+| `tagger_vocab_with_categories.json` | Same without alias data |
+| `tagger_vocab.json` | Minimal vocab — `{"idx2tag": [...]}` only |
+| `inference_tagger_standalone.py` | Self-contained CLI inference script (no `transformers` dep) |
 | `tagger_ui_server.py` | FastAPI + Jinja2 web UI server |
+| `requirements.txt` | Python dependencies |
 
 ## Tag Vocabulary
 
@@ -85,8 +141,7 @@ Minimum tag frequency threshold: **50** occurrences across the combined dataset.
 
 ## Limitations
 
-- Evaluated on booru-style illustrations and furry art; performance on photographic
-  images or other art styles is untested.
+- Evaluated on booru-style illustrations and furry art; performance on photographic images or other art styles is untested.
 - The vocabulary reflects the biases of e621 and Danbooru annotation practices.
 
 ## License