alessandro54/pettrace-reid-e5

PetTrace Re-ID E5

Research artifact for open-set cat and dog re-identification. The bundle combines the frozen E4 visual encoder with the configuration and evidence for E5's identity-agnostic, double-gated morphological reranker.

Pipeline

1. YOLOv8n localizes the animal.
2. A CLIP ViT-B/32 encoder adapted with an MLP projection head and LoRA produces an L2-normalized 512-dimensional embedding.
3. Cosine similarity ranks gallery identities using maximum photo aggregation.
4. E5 opens a reranking gate only for visually ambiguous Top-5 results and applies compatibility scores from a closed vocabulary of observable coat and morphology attributes.

E5 does not train a second encoder. The files at the repository root are the frozen E4 visual pipeline used by E5. The e5/ directory contains its immutable calibration, experiment design, control receipt and aggregate evaluation results.

Versioned artifact

• PetTrace package: pettrace-ml==0.2.46
• Source commit: 2d77426
• Visual model: clip-vit-b32-crop-lora-e3-v4.100@v3
• Seed / selected epoch: 46 / 27
• Encoder SHA-256: aaa922be105009c539985d241036999f55f18bef3806f2b02c6894cddc884ebe
• Detector SHA-256: da8f9b9ebea5157cdcefa7bea9fd782249ebdf119f917c07d64e5b41942b9c9d
• Attribute model: Qwen/Qwen3-VL-2B-Instruct@89644892e4d85e24eaac8bacfd4f463576704203
• Attribute prompt SHA-256: 55519559059aeee3d8a1427eff8f78a3c2400957edd50f2d2a82f38e6383f6a5
• Frozen E5 parameters: tau_v=0.01, lambda=0.02, tau_t=0.05

Named tags such as v1 are for readability. Reproducible use should pin the immutable Hugging Face commit returned for this release.

Results

Dataset	Condition	Rank-1	Rank-2	Rank-5	mAP	Gate	Rescued	Damaged
Public v2	E4 baseline	85.56%	96.03%	99.28%	0.8345	0.00%	0	0
Public v2	Double-gated E5	85.92%	96.03%	99.28%	0.8346	13.72%	4	3
PetTrace v6	E4 baseline	86.25%	94.22%	99.00%	0.7333	0.00%	0	0
PetTrace v6	Double-gated E5	87.45%	94.62%	99.00%	0.7346	12.75%	8	2

Thresholds were selected only on the public validation split. Public v2 and PetTrace v6 were read once after freezing. The paired Rank-1 changes are exploratory: exact two-sided McNemar p-values are 1.000 for Public v2 and 0.109 for PetTrace v6, so the observed gains are not claimed as statistically significant.

Loading the visual pipeline

from pettrace.models.artifacts import download_model, load_model

artifact = download_model("alessandro54/pettrace-reid-e5", revision="v1")
model = load_model(artifact)
embedding = model.pipeline.embed("pet.jpg")

The full E5 evaluation is reproduced by notebooks/e5_language_reranking.ipynb. The reranker configuration is stored in e5/calibration.json; e5/experiment-design.json records all model and dataset revisions.

Intended use

This artifact is intended for research, benchmarking and human-assisted lost-pet candidate ranking. It is not biometric proof of identity and must not autonomously trigger ownership, enforcement, medical or safety decisions. Performance can degrade under poor localization, occlusion, severe pose changes, rare appearances and visually similar animals.

Data and privacy

The public training and public evaluation releases are available on Hugging Face. PetTrace v6 is a separate private benchmark and is not redistributed here. The mixed E5 attribute cache, per-query scores, filenames and identity labels are intentionally excluded because they include PetTrace v6. Only aggregate private-benchmark metrics are included.

The VLM received only frozen YOLO crops. It did not receive filenames, folder names, animal IDs or other identity metadata.

Licenses and attribution

This model repository is marked AGPL-3.0 because it redistributes an Ultralytics YOLOv8n detector. The PetTrace source code is separately licensed under MIT. The encoder derives from openai/clip-vit-base-patch32, and E5 used Qwen/Qwen3-VL-2B-Instruct offline without redistributing its weights. Each upstream component remains subject to its own license and terms.

Citation

This is a thesis research artifact. A citable paper reference and archival DOI will be added after publication. Until then, cite this immutable model revision together with the source commit and the two refined dataset revisions recorded in e5/experiment-design.json.