Fix: README.md - Colab-ready instructions + suppress char/digit/country/stl labels

README.md

@@ -101,12 +101,17 @@ A single fine-tuned **ConvNeXt-Small** model that identifies a wide range of sub
 
 ## Quick Start
 
+> **Google Colab / fresh environment:** run `!pip install -q transformers torchvision safetensors Pillow huggingface_hub` first.
+
 ```python
+from transformers import AutoModelForImageClassification
 from PIL import Image
-from photo_identifier import PhotoIdentifierModel, PhotoIdentifierConfig
 
-# Load from HuggingFace Hub
-model = PhotoIdentifierModel.from_pretrained("BlakePeavy/photo-identifier-v3")
+# Load from HuggingFace Hub (trust_remote_code required for custom backbone)
+model = AutoModelForImageClassification.from_pretrained(
+    "BlakePeavy/photo-identifier-v3",
+    trust_remote_code=True,
+)
 model.eval()
 
 # Run inference
@@ -126,40 +131,67 @@ for label, score in results:
 
 ### Using `transformers` pipeline
 
+The image processor must be loaded explicitly because this model uses a
+custom `model_type` not registered in the default transformers auto-registry.
+
 ```python
-from transformers import pipeline
+from transformers import pipeline, AutoImageProcessor
 
+# Load the image processor from the repo's preprocessor_config.json
+processor = AutoImageProcessor.from_pretrained(
+    "BlakePeavy/photo-identifier-v3",
+    use_fast=False,
+)
 pipe = pipeline(
     "image-classification",
     model="BlakePeavy/photo-identifier-v3",
+    image_processor=processor,
     trust_remote_code=True,
 )
 results = pipe("my_photo.jpg", top_k=5)
+for r in results:
+    print(f"{r['score']:.1%}  {r['label']}")
 ```
 
 ---
 
 ## Loading the Model Manually
 
+Useful when you want plain PyTorch with no `transformers` dependency.
+The weights are stored as `model.safetensors` (not `pytorch_model.bin`).
+Keys have a `convnext.` prefix that must be stripped before loading into
+a bare `torchvision.models.convnext_small`.
+
 ```python
+# !pip install -q torch torchvision safetensors Pillow huggingface_hub
 import torch
 import json
 from torchvision import models, transforms
+from safetensors.torch import load_file
+from huggingface_hub import hf_hub_download
 from PIL import Image
 
-# Load metadata
-with open("config.json") as f:
+REPO = "BlakePeavy/photo-identifier-v3"
+
+# Download model files
+config_path  = hf_hub_download(REPO, "config.json")
+weights_path = hf_hub_download(REPO, "model.safetensors")
+
+# Load label map
+with open(config_path) as f:
     cfg = json.load(f)
-classes = cfg["id2label"]  # {0: "class_name", ...}
+classes = cfg["id2label"]  # {"0": "class_name", ...}
 
-# Rebuild the backbone
-model = models.convnext_small()
+# Rebuild the backbone (weights=None — we load from safetensors below)
+model = models.convnext_small(weights=None)
 in_f = model.classifier[-1].in_features
 model.classifier[-1] = torch.nn.Linear(in_f, len(classes))
 
-# Load EMA weights
-ck = torch.load("pytorch_model.bin", map_location="cpu", weights_only=False)
-model.load_state_dict(ck)
+# Load from safetensors — strip the "convnext." wrapper prefix
+sd = load_file(weights_path)
+sd = {k.replace("convnext.", "", 1): v for k, v in sd.items()
+      if k.startswith("convnext.")}
+model.load_state_dict(sd)
 model.eval()
 
 # Preprocess