deploy: sync encoder from 26315a9

README.md

@@ -10,12 +10,39 @@ pinned: false
 
 # Reflections SigLIP text-query encoder
 
-Embeds a natural-language query into a 768-d L2-normalized vector using the
-SigLIP2 text tower (`onnx-community/siglip2-base-patch16-256-ONNX`), in the same
-cosine space as the photo image embeddings.
+Embeds a natural-language search query into a 768-d L2-normalized vector using the
+SigLIP2 text tower (`onnx-community/siglip2-base-patch16-256-ONNX`) — the same
+checkpoint the photo image embeddings use, so query and image vectors share one
+cosine space. The model is baked into the Docker image at build time and stays
+resident in RAM, so requests never pay a download or load cost.
+
+## How it fits in
+
+```
+Browser ──/gallery?q=…──▶ Vercel web app
+                             │  POST /encode  (Bearer $SIGLIP_ENCODER_TOKEN)
+                             ▼
+                         this Space ──▶ {vector:[768]}   (model resident in RAM)
+                             │
+   Vercel cosine-ranks that vector against image embeddings in Neon (pgvector)
+                             ▼
+                         ranked photos
+
+Deploy:  push to main (encoder/**) ─▶ GitHub Actions ─(OIDC, no stored token)─▶ hf upload ─▶ Space rebuilds
+Warm:    GitHub Actions cron ─every 6h─▶ GET /health   (keeps the Space under HF's 48h sleep)
+```
+
+## API
 
 - `POST /encode` — `{ "query": "..." }` → `{ "vector": [768 floats] }`. Requires
   `Authorization: Bearer $SIGLIP_ENCODER_TOKEN`.
-- `GET /health` — liveness for the keep-warm cron.
+- `GET /health` — open liveness check for the keep-warm cron.
+
+## Operating
 
-Set the Space secret `SIGLIP_ENCODER_TOKEN`. The model is baked into the image.
+- **Secret:** set `SIGLIP_ENCODER_TOKEN` on the Space; it must match the web app's
+  value (the web app sends it as the bearer token).
+- **Deploy:** automatic on push to `main` touching `encoder/**`, via Trusted
+  Publishing (OIDC) — no HF token is stored anywhere.
+- **Model:** downloaded once during the image build and baked in; container
+  starts (including post-sleep wakes) load it from local disk, never the network.