Move region indexes to HF dataset (geobot-indexes); load on demand via hf_hub_download

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+WORKDIR /app
+ENV HF_HOME=/app/hf-cache \
+    PYTHONUNBUFFERED=1
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+ && pip install --no-cache-dir -r requirements.txt
+
+# Bake BOTH switchable CLIP models into the image (Space disk is non-persistent at runtime).
+RUN python - <<'PY'
+from transformers import CLIPVisionModelWithProjection, CLIPImageProcessor
+for mid in ("openai/clip-vit-base-patch32", "openai/clip-vit-large-patch14", "geolocal/StreetCLIP"):
+    CLIPVisionModelWithProjection.from_pretrained(mid)
+    CLIPImageProcessor.from_pretrained(mid)
+PY
+
+COPY . .
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -0,0 +1,26 @@
+---
+title: GeoBot
+emoji: 🌍
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# GeoBot
+
+A tiny, fully self-hosted AI opponent for a GeoGuessr-style game. It receives two
+Street View images (headings ~0° and ~180°) and returns a country guess with a
+coordinate and human-readable reasoning.
+
+It does **no training and no external AI calls**. It embeds the two images with
+CLIP (`openai/clip-vit-base-patch32`, vision tower only, CPU) and retrieves the
+nearest examples from a precomputed index of visual geography clues, votes on a
+country, and fills reasoning templates from the matched clue labels.
+
+- `POST /guess` — multipart `image0`, `image180`; header `X-API-Key`.
+- `GET /health` — liveness + index size (also the wake-up ping target).
+
+Geographic clue knowledge derived from the community guides at
+[plonkit.net](https://plonkit.net) (embeddings only; no images redistributed).

app.py

@@ -0,0 +1,229 @@
+"""Phase 2 — FastAPI inference service for the HF Docker Space (port 7860).
+
+Loads ALL switchable CLIP models + their indexes once at startup, asserts each
+index matches its model, then serves POST /guess (multipart, X-API-Key) and
+GET /health (no auth). Pick a model per request with ?model=fast|pro.
+"""
+
+import io
+import json
+import os
+import sys
+import time
+from collections import Counter
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import numpy as np
+from fastapi import FastAPI, File, Header, HTTPException, Query, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "shared"))
+from version import MODELS, DEFAULT_MODEL  # noqa: E402
+from embedder import Embedder  # noqa: E402
+import guess as guesslib  # noqa: E402
+import atlas as atlaslib  # noqa: E402
+import region as regionlib  # noqa: E402
+
+DATA = Path(__file__).resolve().parent / "data"
+API_KEY = os.environ.get("API_KEY", "")
+ALLOWED_ORIGIN = os.environ.get("ALLOWED_ORIGIN", "*")
+MAX_BYTES = 4 * 1024 * 1024
+RATE_LIMIT_PER_MIN = 30
+
+# Region kNN indexes live in a free HF Dataset repo (the 1GB Space can't hold them all).
+# Resolve a region file from local data/ if present, else download from the dataset (cached).
+INDEX_DATASET = os.environ.get("INDEX_DATASET", "GeoguessrAngular/geobot-indexes")
+
+
+def region_file_path(fname):
+    local = DATA / fname
+    if local.exists():
+        return local
+    from huggingface_hub import hf_hub_download
+    return Path(hf_hub_download(repo_id=INDEX_DATASET, filename=fname, repo_type="dataset"))
+
+Image.MAX_IMAGE_PIXELS = 50_000_000
+
+STATE = {}
+_req_times = []  # global in-memory rate limiter timestamps
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    centroids = json.loads((DATA / "centroids.json").read_text(encoding="utf-8"))
+    priors_path = DATA / "priors.json"
+    priors = json.loads(priors_path.read_text(encoding="utf-8")) if priors_path.exists() else None
+
+    models = {}
+    embedder_cache = {}   # model_id -> Embedder (heavy weights loaded once)
+    index_cache = {}      # index_file -> (index, rows, count, model_id, index_version)
+    for key, m in MODELS.items():
+        if m["model_id"] not in embedder_cache:
+            embedder_cache[m["model_id"]] = Embedder(m["model_id"])
+
+        # --- region kNN locator (e.g. Serbia) ---
+        if m.get("region_file"):
+            ref_emb, ref_lat, ref_lng = regionlib.load_region(region_file_path(m["region_file"]))
+            models[key] = {
+                "type": "region", "embedder": embedder_cache[m["model_id"]],
+                "ref_emb": ref_emb, "ref_lat": ref_lat, "ref_lng": ref_lng,
+                "country_slug": m.get("country_slug", key), "country_name": m.get("country_name", key),
+                "model_id": m["model_id"], "label": m.get("label", key),
+            }
+            print(f"Loaded model '{key}': region kNN {ref_emb.shape}, {m['model_id']}")
+            continue
+
+        # --- learned classifier head (Atlas) ---
+        if m.get("head_file"):
+            W, b, classes = atlaslib.load_head(DATA / m["head_file"])
+            models[key] = {
+                "type": "head", "embedder": embedder_cache[m["model_id"]],
+                "W": W, "b": b, "classes": classes,
+                "model_id": m["model_id"], "label": m.get("label", key),
+            }
+            print(f"Loaded model '{key}': head W{W.shape} {len(classes)} classes, {m['model_id']}")
+            continue
+
+        # --- retrieval (index) model ---
+        if m["index_file"] not in index_cache:
+            meta = json.loads((DATA / m["meta_file"]).read_text(encoding="utf-8"))
+            index = np.load(DATA / m["index_file"]).astype(np.float32)
+            rows = meta["rows"]
+            assert index.shape[0] == len(rows), f"[{key}] index/meta row mismatch"
+            index_cache[m["index_file"]] = (
+                index, rows, Counter(r["country"] for r in rows),
+                meta["model_id"], meta["index_version"])
+        index, rows, count, meta_mid, meta_iv = index_cache[m["index_file"]]
+        if meta_mid != m["model_id"] or meta_iv != m["index_version"]:
+            raise RuntimeError(
+                f"[{key}] index/version mismatch: meta has {meta_mid}/{meta_iv}, "
+                f"expected {m['model_id']}/{m['index_version']}")
+
+        text_vecs, text_countries = None, None
+        if m.get("text_file"):
+            text_vecs = np.load(DATA / m["text_file"]).astype(np.float32)
+            text_countries = json.loads((DATA / m["text_countries_file"]).read_text(encoding="utf-8"))
+
+        models[key] = {
+            "type": "retrieval", "embedder": embedder_cache[m["model_id"]],
+            "index": index, "rows": rows, "count": count,
+            "model_id": m["model_id"], "index_version": m["index_version"],
+            "label": m.get("label", key),
+            "text_vecs": text_vecs, "text_countries": text_countries,
+        }
+        print(f"Loaded model '{key}': index {index.shape}, {m['model_id']} {m['index_version']}"
+              f"{', +zeroshot-text' if text_vecs is not None else ''}")
+
+    # Optional script (writing-system) branch for the Atlas head.
+    script_vecs = script_names = country_scripts = None
+    if (DATA / "script_text.npy").exists() and (DATA / "country_scripts.json").exists():
+        script_vecs = np.load(DATA / "script_text.npy").astype(np.float32)
+        script_names = json.loads((DATA / "script_names.json").read_text(encoding="utf-8"))
+        country_scripts = json.loads((DATA / "country_scripts.json").read_text(encoding="utf-8"))
+        print(f"Loaded script branch: {len(script_names)} scripts, {len(country_scripts)} country maps")
+
+    STATE["models"] = models
+    STATE["centroids"] = centroids
+    STATE["priors"] = priors
+    STATE["script_vecs"] = script_vecs
+    STATE["script_names"] = script_names
+    STATE["country_scripts"] = country_scripts
+    STATE["cfg"] = guesslib.Config()
+    print(f"Ready. models={list(models)} default={DEFAULT_MODEL} "
+          f"centroids={len(centroids)} priors={len(priors) if priors else 0}")
+    yield
+    STATE.clear()
+
+
+app = FastAPI(title="GeoBot", lifespan=lifespan)
+app.add_middleware(CORSMiddleware, allow_origins=[ALLOWED_ORIGIN] if ALLOWED_ORIGIN != "*" else ["*"],
+                   allow_methods=["*"], allow_headers=["*"])
+
+
+def _check_key(x_api_key):
+    if not API_KEY:
+        return  # unset key disables auth (local dev)
+    if x_api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="bad or missing API key")
+
+
+def _rate_limit():
+    now = time.time()
+    cutoff = now - 60
+    while _req_times and _req_times[0] < cutoff:
+        _req_times.pop(0)
+    if len(_req_times) >= RATE_LIMIT_PER_MIN:
+        raise HTTPException(status_code=429, detail="rate limited")
+    _req_times.append(now)
+
+
+async def _read_image(upload: UploadFile):
+    raw = await upload.read()
+    if len(raw) > MAX_BYTES:
+        raise HTTPException(status_code=413, detail="image too large (>4 MB)")
+    try:
+        return Image.open(io.BytesIO(raw)).convert("RGB")
+    except Exception:
+        raise HTTPException(status_code=400, detail="undecodable image")
+
+
+@app.get("/health")
+def health():
+    models = STATE.get("models", {})
+    return {
+        "status": "ok",
+        "default_model": DEFAULT_MODEL,
+        "models": {
+            k: {"type": v.get("type"), "model_id": v["model_id"], "label": v["label"],
+                **({"index_size": int(v["index"].shape[0]), "index_version": v["index_version"]}
+                   if v.get("type") == "retrieval" else
+                   {"refs": int(v["ref_emb"].shape[0])} if v.get("type") == "region" else
+                   {"classes": len(v["classes"])})}
+            for k, v in models.items()
+        },
+    }
+
+
+@app.post("/guess")
+async def do_guess(images: list[UploadFile] = File(None),
+                   image0: UploadFile = File(None), image180: UploadFile = File(None),
+                   skill: float = Query(1.0, ge=0.0, le=1.0),
+                   model: str = Query(DEFAULT_MODEL),
+                   x_api_key: str = Header(None, alias="X-API-Key")):
+    _check_key(x_api_key)
+    _rate_limit()
+    # Accept either N frames under repeated field "images", or legacy image0/image180.
+    uploads = [u for u in (images or []) if u is not None]
+    if not uploads:
+        uploads = [u for u in (image0, image180) if u is not None]
+    if not uploads:
+        raise HTTPException(status_code=400, detail="no images")
+    key = model if model in STATE["models"] else DEFAULT_MODEL
+    M = STATE["models"][key]
+    t0 = time.time()
+    pil = [await _read_image(u) for u in uploads]
+    emb = M["embedder"].embed(pil)
+    try:
+        if M.get("type") == "region":
+            result = regionlib.predict(list(emb), M["ref_emb"], M["ref_lat"], M["ref_lng"],
+                                       M["country_slug"], M["country_name"])
+        elif M.get("type") == "head":
+            result = atlaslib.predict(list(emb), M["W"], M["b"], M["classes"],
+                                      STATE["centroids"], STATE["cfg"], STATE["priors"],
+                                      STATE["script_vecs"], STATE["script_names"],
+                                      STATE["country_scripts"])
+        else:
+            result = guesslib.guess(list(emb), M["index"], M["rows"],
+                                    STATE["centroids"], M["count"], STATE["cfg"],
+                                    STATE["priors"], M["text_vecs"], M["text_countries"])
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"guess failed: {type(e).__name__}")
+    result["timing_ms"] = int((time.time() - t0) * 1000)
+    result["model"] = key
+    result["model_id"] = M["model_id"]
+    result["index_version"] = M.get("index_version")
+    print(f"[{key}] guess winner={result['country']} conf={result['confidence']} "
+          f"ms={result['timing_ms']}")
+    return result

atlas.py

@@ -0,0 +1,127 @@
+"""Atlas — the LEARNED model's inference. A linear classifier head on top of the
+frozen StreetCLIP embedding: probs = softmax(emb @ W + b) over playable countries,
+averaged across the round's frames, then weighted by the game-location prior.
+
+Unlike guess.py (nearest-neighbour retrieval), this is a trained model: it learned
+what distinguishes each country from all PlonkIt + geohints images.
+"""
+
+import numpy as np
+
+ASSERTIVE = [
+    "I've learned to read scenes like this as {country} — the overall mix of road, signage and surroundings fits.",
+    "This reads clearly as {country} to me, weighing everything in view.",
+    "Confident on {country}: the combination of cues I trained on lines up.",
+    "My read is {country} — the whole scene matches what I know for it.",
+]
+HEDGED = [
+    "Looks most like {country}, though {runner} crossed my mind. Going with {country}.",
+    "Leaning {country} here; {runner} was the next best. Committing to {country}.",
+    "Probably {country} — {runner} was close, but I'll take {country}.",
+    "My best read is {country}, with {runner} as a maybe.",
+]
+UNCERTAIN = [
+    "Tough scene — nothing jumps out, but it leans {country}, so that's my guess.",
+    "Low confidence, but the overall feel points to {country}.",
+    "Hard to read; I'll take {country} as the most likely.",
+    "Not sure, but {country} fits best, so guessing there.",
+]
+
+
+def load_head(path):
+    z = np.load(path, allow_pickle=True)
+    return (z["W"].astype(np.float32), z["b"].astype(np.float32),
+            [str(c) for c in z["classes"]])
+
+
+def _pick(variants, seed_text):
+    return variants[abs(hash(seed_text)) % len(variants)]
+
+
+SCRIPT_PENALTY = 0.15   # multiply prob of countries that don't use the detected (non-Latin) script
+# Only these distinctive scripts are reliable zero-shot; sinhala/lao/bengali/etc. are
+# noisy attractors that misfire on text-less scenes, so they're excluded from detection.
+RELIABLE_SCRIPTS = {"thai", "cyrillic", "greek", "cjk", "devanagari", "arabic", "hebrew"}
+SCRIPT_MARGIN = 0.015   # the detected script must beat Latin by at least this
+
+
+def _detect_script(embs, script_vecs, script_names):
+    """Return the detected writing system, or None (Latin / text-less / uncertain).
+    Fires only when a RELIABLE non-Latin script clearly beats Latin."""
+    if "latin" not in script_names:
+        return None
+    sims = np.zeros(len(script_names))
+    for e in embs:
+        sims += script_vecs @ e
+    sims /= len(embs)
+    latin = sims[script_names.index("latin")]
+    best, best_s = None, -1e9
+    for i, name in enumerate(script_names):
+        if name in RELIABLE_SCRIPTS and sims[i] > best_s:
+            best, best_s = name, sims[i]
+    return best if best is not None and (best_s - latin) >= SCRIPT_MARGIN else None
+
+
+def predict(embs, W, b, classes, centroids, cfg, priors=None,
+            script_vecs=None, script_names=None, country_scripts=None):
+    """embs: list of (768,) StreetCLIP embeddings. Returns the response dict."""
+    if not isinstance(embs, (list, tuple)):
+        embs = [embs]
+    probs = np.zeros(len(classes), dtype=np.float64)
+    for e in embs:
+        logits = e @ W + b
+        logits = logits - logits.max()
+        ex = np.exp(logits)
+        probs += ex / ex.sum()
+    probs /= len(embs)
+
+    # weight by the game-location prior (and hard-filter 0-location countries)
+    if priors is not None:
+        for i, c in enumerate(classes):
+            av = priors.get(c, 0)
+            probs[i] = 0.0 if av <= 0 else probs[i] * (av ** cfg.PRIOR_BETA)
+        s = probs.sum()
+        if s > 0:
+            probs /= s
+
+    # script branch: if a distinctive (non-Latin) writing system is detected,
+    # down-weight countries that don't use it (Thai → only Thailand, etc.)
+    detected = None
+    if script_vecs is not None and country_scripts is not None:
+        detected = _detect_script(embs, script_vecs, script_names)
+        if detected:
+            for i, c in enumerate(classes):
+                if detected not in country_scripts.get(c, ["latin"]):
+                    probs[i] *= SCRIPT_PENALTY
+            s = probs.sum()
+            if s > 0:
+                probs /= s
+
+    order = np.argsort(-probs)
+    winner = classes[order[0]]
+    confidence = float(probs[order[0]])
+    runner = classes[order[1]] if len(order) > 1 else None
+    cen = centroids[winner]
+    runner_name = centroids.get(runner, {}).get("name", runner) if runner else None
+
+    seed = winner + f"{confidence:.2f}"
+    if confidence >= 0.55:
+        reasoning = _pick(ASSERTIVE, seed).format(country=cen["name"])
+    elif confidence >= 0.30:
+        reasoning = _pick(HEDGED, seed).format(country=cen["name"], runner=runner_name or "a neighbour")
+    else:
+        reasoning = _pick(UNCERTAIN, seed).format(country=cen["name"])
+    if detected:
+        reasoning += f" (I can see {detected} script, which points here.)"
+
+    return {
+        "lat": cen["lat"], "lon": cen["lon"],
+        "country": winner, "country_name": cen["name"],
+        "confidence": round(confidence, 3),
+        "runner_up": runner,
+        "runner_up_name": runner_name,
+        "runner_up_conf": round(float(probs[order[1]]), 3) if len(order) > 1 else None,
+        "reasoning": reasoning,
+        "clues": [],
+        "script": detected,
+    }

data/atlas_head.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8bf5bc3985fee140b7a5b323434e5d27f66c325619004b89afdd85a87bdd5ede
+size 352815

data/centroids.json

@@ -0,0 +1,818 @@
+{
+  "alaska": {
+    "lat": 64.2,
+    "lon": -149.49,
+    "name": "Alaska",
+    "src": "hardcoded"
+  },
+  "albania": {
+    "lat": 41.14564,
+    "lon": 20.00649,
+    "name": "Albania",
+    "src": "Albania"
+  },
+  "american-samoa": {
+    "lat": -14.31113,
+    "lon": -170.75345,
+    "name": "American Samoa",
+    "src": "American Samoa"
+  },
+  "andorra": {
+    "lat": 42.53604,
+    "lon": 1.56174,
+    "name": "Andorra",
+    "src": "Andorra"
+  },
+  "antarctica": {
+    "lat": -76.60565,
+    "lon": 66.27535,
+    "name": "Antarctica",
+    "src": "Antarctica"
+  },
+  "argentina": {
+    "lat": -37.0905,
+    "lon": -63.96988,
+    "name": "Argentina",
+    "src": "Argentina"
+  },
+  "australia": {
+    "lat": -24.92291,
+    "lon": 133.08113,
+    "name": "Australia",
+    "src": "Australia"
+  },
+  "austria": {
+    "lat": 47.69458,
+    "lon": 14.7636,
+    "name": "Austria",
+    "src": "Austria"
+  },
+  "azores": {
+    "lat": 37.80081,
+    "lon": -25.4669,
+    "name": "Azores",
+    "src": "Azores"
+  },
+  "bangladesh": {
+    "lat": 23.67772,
+    "lon": 89.85934,
+    "name": "Bangladesh",
+    "src": "Bangladesh"
+  },
+  "belarus": {
+    "lat": 53.69944,
+    "lon": 28.01873,
+    "name": "Belarus",
+    "src": "Belarus"
+  },
+  "belgium": {
+    "lat": 51.09263,
+    "lon": 4.16957,
+    "name": "Belgium",
+    "src": "Flemish"
+  },
+  "bermuda": {
+    "lat": 32.3192,
+    "lon": -64.72802,
+    "name": "Bermuda",
+    "src": "Bermuda"
+  },
+  "bhutan": {
+    "lat": 27.52397,
+    "lon": 90.29573,
+    "name": "Bhutan",
+    "src": "Bhutan"
+  },
+  "bolivia": {
+    "lat": -16.28784,
+    "lon": -64.28579,
+    "name": "Bolivia",
+    "src": "Bolivia"
+  },
+  "botswana": {
+    "lat": -22.3453,
+    "lon": 24.47144,
+    "name": "Botswana",
+    "src": "Botswana"
+  },
+  "brazil": {
+    "lat": -14.23886,
+    "lon": -49.72801,
+    "name": "Brazil",
+    "src": "Brazil"
+  },
+  "british-indian-ocean-territory": {
+    "lat": -6.19232,
+    "lon": 71.34757,
+    "name": "British Indian Ocean Territory",
+    "src": "Br. Indian Ocean Ter."
+  },
+  "bulgaria": {
+    "lat": 42.73222,
+    "lon": 25.18968,
+    "name": "Bulgaria",
+    "src": "Bulgaria"
+  },
+  "cambodia": {
+    "lat": 12.55877,
+    "lon": 105.10263,
+    "name": "Cambodia",
+    "src": "Cambodia"
+  },
+  "canada": {
+    "lat": 56.83692,
+    "lon": -110.43087,
+    "name": "Canada",
+    "src": "Canada"
+  },
+  "chile": {
+    "lat": -35.71034,
+    "lon": -71.4964,
+    "name": "Chile",
+    "src": "Chile"
+  },
+  "china": {
+    "lat": 36.90367,
+    "lon": 98.60392,
+    "name": "China",
+    "src": "China"
+  },
+  "christmas-island": {
+    "lat": -10.49635,
+    "lon": 105.64974,
+    "name": "Christmas Island",
+    "src": "Christmas I."
+  },
+  "cocos-islands": {
+    "lat": -12.17779,
+    "lon": 96.91627,
+    "name": "Cocos Islands",
+    "src": "Cocos Is."
+  },
+  "colombia": {
+    "lat": 4.11347,
+    "lon": -72.58619,
+    "name": "Colombia",
+    "src": "Colombia"
+  },
+  "costa-rica": {
+    "lat": 9.62102,
+    "lon": -83.6334,
+    "name": "Costa Rica",
+    "src": "Costa Rica"
+  },
+  "croatia": {
+    "lat": 44.74512,
+    "lon": 15.32158,
+    "name": "Croatia",
+    "src": "Croatia"
+  },
+  "curacao": {
+    "lat": 12.21206,
+    "lon": -69.03453,
+    "name": "Curaçao",
+    "src": "Curaçao"
+  },
+  "cyprus": {
+    "lat": 34.90489,
+    "lon": 32.97995,
+    "name": "Cyprus",
+    "src": "Cyprus"
+  },
+  "czechia": {
+    "lat": 49.80045,
+    "lon": 15.51259,
+    "name": "Czechia",
+    "src": "Czechia"
+  },
+  "denmark": {
+    "lat": 56.27434,
+    "lon": 9.26047,
+    "name": "Denmark",
+    "src": "Denmark"
+  },
+  "dominican-republic": {
+    "lat": 18.77655,
+    "lon": -70.12528,
+    "name": "Dominican Republic",
+    "src": "Dominican Rep."
+  },
+  "ecuador": {
+    "lat": -1.78872,
+    "lon": -78.28143,
+    "name": "Ecuador",
+    "src": "Ecuador"
+  },
+  "egypt": {
+    "lat": 26.82439,
+    "lon": 29.46414,
+    "name": "Egypt",
+    "src": "Egypt"
+  },
+  "estonia": {
+    "lat": 58.58849,
+    "lon": 25.49317,
+    "name": "Estonia",
+    "src": "Estonia"
+  },
+  "eswatini": {
+    "lat": -26.53957,
+    "lon": 31.44785,
+    "name": "Eswatini",
+    "src": "eSwatini"
+  },
+  "falkland-islands": {
+    "lat": -51.79424,
+    "lon": -58.61389,
+    "name": "Falkland Islands",
+    "src": "Falkland Is."
+  },
+  "faroe-islands": {
+    "lat": 62.19918,
+    "lon": -6.78831,
+    "name": "Faroe Islands",
+    "src": "Faeroe Is."
+  },
+  "finland": {
+    "lat": 64.94389,
+    "lon": 27.41573,
+    "name": "Finland",
+    "src": "Finland"
+  },
+  "france": {
+    "lat": 46.6,
+    "lon": 2.5,
+    "name": "France",
+    "src": "manual (metropolitan France — NE polygon repr. point fell in French Guiana)"
+  },
+  "germany": {
+    "lat": 51.08513,
+    "lon": 10.48123,
+    "name": "Germany",
+    "src": "Germany"
+  },
+  "ghana": {
+    "lat": 7.95184,
+    "lon": -1.07721,
+    "name": "Ghana",
+    "src": "Ghana"
+  },
+  "gibraltar": {
+    "lat": 36.12684,
+    "lon": -5.34628,
+    "name": "Gibraltar",
+    "src": "Gibraltar"
+  },
+  "greece": {
+    "lat": 39.07032,
+    "lon": 21.95268,
+    "name": "Greece",
+    "src": "Greece"
+  },
+  "greenland": {
+    "lat": 71.811,
+    "lon": -40.33342,
+    "name": "Greenland",
+    "src": "Greenland"
+  },
+  "guam": {
+    "lat": 13.45962,
+    "lon": 144.76055,
+    "name": "Guam",
+    "src": "Guam"
+  },
+  "guatemala": {
+    "lat": 15.77389,
+    "lon": -90.28683,
+    "name": "Guatemala",
+    "src": "Guatemala"
+  },
+  "hawaii": {
+    "lat": 19.9,
+    "lon": -155.58,
+    "name": "Hawaii",
+    "src": "hardcoded"
+  },
+  "hong-kong": {
+    "lat": 22.4112,
+    "lon": 114.056,
+    "name": "Hong Kong",
+    "src": "Hong Kong"
+  },
+  "hungary": {
+    "lat": 47.15799,
+    "lon": 19.11919,
+    "name": "Hungary",
+    "src": "Hungary"
+  },
+  "iceland": {
+    "lat": 64.96471,
+    "lon": -18.46765,
+    "name": "Iceland",
+    "src": "Iceland"
+  },
+  "india": {
+    "lat": 21.78675,
+    "lon": 80.22651,
+    "name": "India",
+    "src": "India"
+  },
+  "indonesia": {
+    "lat": 0.10491,
+    "lon": 113.32523,
+    "name": "Indonesia",
+    "src": "Indonesia"
+  },
+  "iraq": {
+    "lat": 35.93951,
+    "lon": 44.51636,
+    "name": "Iraq",
+    "src": "Iraqi Kurdistan"
+  },
+  "ireland": {
+    "lat": 53.41606,
+    "lon": -7.95824,
+    "name": "Ireland",
+    "src": "Ireland"
+  },
+  "isle-of-man": {
+    "lat": 54.23865,
+    "lon": -4.50997,
+    "name": "Isle of Man",
+    "src": "Isle of Man"
+  },
+  "israel-west-bank": {
+    "lat": 31.44616,
+    "lon": 34.66272,
+    "name": "Israel & the West Bank",
+    "src": "Israel"
+  },
+  "italy": {
+    "lat": 42.49249,
+    "lon": 12.69203,
+    "name": "Italy",
+    "src": "Italy"
+  },
+  "japan": {
+    "lat": 43.46212,
+    "lon": 143.33765,
+    "name": "Japan",
+    "src": "Japan"
+  },
+  "jersey": {
+    "lat": 49.21833,
+    "lon": -2.12238,
+    "name": "Jersey",
+    "src": "Jersey"
+  },
+  "jordan": {
+    "lat": 31.26985,
+    "lon": 36.2997,
+    "name": "Jordan",
+    "src": "Jordan"
+  },
+  "kazakhstan": {
+    "lat": 48.01087,
+    "lon": 66.3259,
+    "name": "Kazakhstan",
+    "src": "Kazakhstan"
+  },
+  "kenya": {
+    "lat": 0.15482,
+    "lon": 37.44792,
+    "name": "Kenya",
+    "src": "Kenya"
+  },
+  "kyrgyzstan": {
+    "lat": 41.22467,
+    "lon": 75.06975,
+    "name": "Kyrgyzstan",
+    "src": "Kyrgyzstan"
+  },
+  "laos": {
+    "lat": 18.20551,
+    "lon": 104.68352,
+    "name": "Laos",
+    "src": "Laos"
+  },
+  "latvia": {
+    "lat": 56.86803,
+    "lon": 24.38329,
+    "name": "Latvia",
+    "src": "Latvia"
+  },
+  "lebanon": {
+    "lat": 33.8692,
+    "lon": 35.90693,
+    "name": "Lebanon",
+    "src": "Lebanon"
+  },
+  "lesotho": {
+    "lat": -29.6153,
+    "lon": 28.16436,
+    "name": "Lesotho",
+    "src": "Lesotho"
+  },
+  "liechtenstein": {
+    "lat": 47.15736,
+    "lon": 9.5351,
+    "name": "Liechtenstein",
+    "src": "Liechtenstein"
+  },
+  "lithuania": {
+    "lat": 55.17273,
+    "lon": 24.14687,
+    "name": "Lithuania",
+    "src": "Lithuania"
+  },
+  "luxembourg": {
+    "lat": 49.80704,
+    "lon": 6.06511,
+    "name": "Luxembourg",
+    "src": "Luxembourg"
+  },
+  "macau": {
+    "lat": 22.13618,
+    "lon": 113.55943,
+    "name": "Macau",
+    "src": "Macao"
+  },
+  "madagascar": {
+    "lat": -18.76902,
+    "lon": 46.72857,
+    "name": "Madagascar",
+    "src": "Madagascar"
+  },
+  "madeira": {
+    "lat": 32.75674,
+    "lon": -16.95071,
+    "name": "Madeira",
+    "src": "Madeira"
+  },
+  "malaysia": {
+    "lat": 3.98945,
+    "lon": 102.11153,
+    "name": "Malaysia",
+    "src": "Malaysia"
+  },
+  "mali": {
+    "lat": 17.60567,
+    "lon": -0.75406,
+    "name": "Mali",
+    "src": "Mali"
+  },
+  "malta": {
+    "lat": 35.89501,
+    "lon": 14.43814,
+    "name": "Malta",
+    "src": "Malta"
+  },
+  "martinique": {
+    "lat": 14.64433,
+    "lon": -61.01815,
+    "name": "Martinique",
+    "src": "Martinique"
+  },
+  "mexico": {
+    "lat": 23.62927,
+    "lon": -102.25815,
+    "name": "Mexico",
+    "src": "Mexico"
+  },
+  "monaco": {
+    "lat": 43.74161,
+    "lon": 7.40293,
+    "name": "Monaco",
+    "src": "Monaco"
+  },
+  "mongolia": {
+    "lat": 46.85869,
+    "lon": 105.40843,
+    "name": "Mongolia",
+    "src": "Mongolia"
+  },
+  "montenegro": {
+    "lat": 42.70141,
+    "lon": 19.28945,
+    "name": "Montenegro",
+    "src": "Montenegro"
+  },
+  "namibia": {
+    "lat": -22.95749,
+    "lon": 17.23377,
+    "name": "Namibia",
+    "src": "Namibia"
+  },
+  "nepal": {
+    "lat": 28.37663,
+    "lon": 83.10311,
+    "name": "Nepal",
+    "src": "Nepal"
+  },
+  "netherlands": {
+    "lat": 52.10563,
+    "lon": 5.51641,
+    "name": "Netherlands",
+    "src": "Netherlands"
+  },
+  "new-zealand": {
+    "lat": -43.59547,
+    "lon": 171.23435,
+    "name": "New Zealand",
+    "src": "New Zealand"
+  },
+  "nigeria": {
+    "lat": 9.07622,
+    "lon": 7.93263,
+    "name": "Nigeria",
+    "src": "Nigeria"
+  },
+  "north-macedonia": {
+    "lat": 41.60515,
+    "lon": 21.73102,
+    "name": "North Macedonia",
+    "src": "North Macedonia"
+  },
+  "northern-mariana-islands": {
+    "lat": 14.15843,
+    "lon": 145.21334,
+    "name": "Northern Mariana Islands",
+    "src": "N. Mariana Is."
+  },
+  "norway": {
+    "lat": 64.56244,
+    "lon": 12.67465,
+    "name": "Norway",
+    "src": "Norway"
+  },
+  "oman": {
+    "lat": 20.81733,
+    "lon": 56.96465,
+    "name": "Oman",
+    "src": "Oman"
+  },
+  "pakistan": {
+    "lat": 30.38006,
+    "lon": 70.08668,
+    "name": "Pakistan",
+    "src": "Pakistan"
+  },
+  "panama": {
+    "lat": 8.41721,
+    "lon": -81.46731,
+    "name": "Panama",
+    "src": "Panama"
+  },
+  "peru": {
+    "lat": -9.18342,
+    "lon": -75.76765,
+    "name": "Peru",
+    "src": "Peru"
+  },
+  "philippines": {
+    "lat": 7.698,
+    "lon": 125.24433,
+    "name": "Philippines",
+    "src": "Philippines"
+  },
+  "pitcairn-islands": {
+    "lat": -24.36871,
+    "lon": -128.31689,
+    "name": "Pitcairn Islands",
+    "src": "Pitcairn Is."
+  },
+  "poland": {
+    "lat": 51.91992,
+    "lon": 19.15627,
+    "name": "Poland",
+    "src": "Poland"
+  },
+  "portugal": {
+    "lat": 39.56508,
+    "lon": -8.29157,
+    "name": "Portugal",
+    "src": "Portugal"
+  },
+  "puerto-rico": {
+    "lat": 18.22116,
+    "lon": -66.40149,
+    "name": "Puerto Rico",
+    "src": "Puerto Rico"
+  },
+  "qatar": {
+    "lat": 25.36365,
+    "lon": 51.13794,
+    "name": "Qatar",
+    "src": "Qatar"
+  },
+  "reunion": {
+    "lat": -21.11907,
+    "lon": 55.54424,
+    "name": "Reunion",
+    "src": "Réunion"
+  },
+  "romania": {
+    "lat": 45.96169,
+    "lon": 24.24783,
+    "name": "Romania",
+    "src": "Romania"
+  },
+  "russia": {
+    "lat": 59.46461,
+    "lon": 88.38747,
+    "name": "Russia",
+    "src": "Russia"
+  },
+  "rwanda": {
+    "lat": -1.94732,
+    "lon": 29.98075,
+    "name": "Rwanda",
+    "src": "Rwanda"
+  },
+  "saint-pierre-and-miquelon": {
+    "lat": 46.78162,
+    "lon": -56.19375,
+    "name": "Saint Pierre and Miquelon",
+    "src": "St. Pierre and Miquelon"
+  },
+  "san-marino": {
+    "lat": 43.93418,
+    "lon": 12.43819,
+    "name": "San Marino",
+    "src": "San Marino"
+  },
+  "sao-tome-and-principe": {
+    "lat": 0.21552,
+    "lon": 6.60119,
+    "name": "São Tomé and Príncipe",
+    "src": "São Tomé and Principe"
+  },
+  "senegal": {
+    "lat": 14.48858,
+    "lon": -14.65724,
+    "name": "Senegal",
+    "src": "Senegal"
+  },
+  "serbia": {
+    "lat": 43.66231,
+    "lon": 20.97381,
+    "name": "Serbia",
+    "src": "Serbia"
+  },
+  "singapore": {
+    "lat": 1.36455,
+    "lon": 103.83054,
+    "name": "Singapore",
+    "src": "Singapore"
+  },
+  "slovakia": {
+    "lat": 48.67465,
+    "lon": 19.64504,
+    "name": "Slovakia",
+    "src": "Slovakia"
+  },
+  "slovenia": {
+    "lat": 46.15021,
+    "lon": 14.61594,
+    "name": "Slovenia",
+    "src": "Slovenia"
+  },
+  "south-africa": {
+    "lat": -28.47459,
+    "lon": 26.12089,
+    "name": "South Africa",
+    "src": "South Africa"
+  },
+  "south-georgia-sandwich-islands": {
+    "lat": -54.42978,
+    "lon": -36.49215,
+    "name": "South Georgia & Sandwich Islands",
+    "src": "S. Geo. and the Is."
+  },
+  "south-korea": {
+    "lat": 38.20457,
+    "lon": 127.00228,
+    "name": "South Korea",
+    "src": "Korean DMZ (south)"
+  },
+  "spain": {
+    "lat": 39.89948,
+    "lon": -3.47653,
+    "name": "Spain",
+    "src": "Spain"
+  },
+  "sri-lanka": {
+    "lat": 7.87889,
+    "lon": 80.66733,
+    "name": "Sri Lanka",
+    "src": "Sri Lanka"
+  },
+  "svalbard": {
+    "lat": 79.85177,
+    "lon": 22.69697,
+    "name": "Svalbard",
+    "src": "Svalbard Is."
+  },
+  "sweden": {
+    "lat": 62.19453,
+    "lon": 14.90512,
+    "name": "Sweden",
+    "src": "Sweden"
+  },
+  "switzerland": {
+    "lat": 46.81195,
+    "lon": 8.427,
+    "name": "Switzerland",
+    "src": "Switzerland"
+  },
+  "taiwan": {
+    "lat": 23.61665,
+    "lon": 120.82792,
+    "name": "Taiwan",
+    "src": "Taiwan"
+  },
+  "tanzania": {
+    "lat": -6.35412,
+    "lon": 34.20886,
+    "name": "Tanzania",
+    "src": "Tanzania"
+  },
+  "thailand": {
+    "lat": 13.03238,
+    "lon": 101.69302,
+    "name": "Thailand",
+    "src": "Thailand"
+  },
+  "tunisia": {
+    "lat": 33.79141,
+    "lon": 8.86273,
+    "name": "Tunisia",
+    "src": "Tunisia"
+  },
+  "turkey": {
+    "lat": 38.96105,
+    "lon": 35.47854,
+    "name": "Turkey",
+    "src": "Turkey"
+  },
+  "uganda": {
+    "lat": 1.38017,
+    "lon": 32.6841,
+    "name": "Uganda",
+    "src": "Uganda"
+  },
+  "ukraine": {
+    "lat": 48.79126,
+    "lon": 31.06142,
+    "name": "Ukraine",
+    "src": "Ukraine"
+  },
+  "united-arab-emirates": {
+    "lat": 24.35262,
+    "lon": 55.13711,
+    "name": "United Arab Emirates",
+    "src": "United Arab Emirates"
+  },
+  "united-kingdom": {
+    "lat": 54.64134,
+    "lon": -6.88882,
+    "name": "United Kingdom",
+    "src": "N. Ireland"
+  },
+  "united-states": {
+    "lat": 37.24636,
+    "lon": -99.69843,
+    "name": "United States of America",
+    "src": "United States of America"
+  },
+  "uruguay": {
+    "lat": -32.52663,
+    "lon": -55.81866,
+    "name": "Uruguay",
+    "src": "Uruguay"
+  },
+  "us-virgin-islands": {
+    "lat": 17.73298,
+    "lon": -64.75742,
+    "name": "US Virgin Islands",
+    "src": "U.S. Virgin Is."
+  },
+  "vanuatu": {
+    "lat": -17.67514,
+    "lon": 168.35423,
+    "name": "Vanuatu",
+    "src": "Vanuatu"
+  },
+  "vietnam": {
+    "lat": 15.96243,
+    "lon": 107.85285,
+    "name": "Vietnam",
+    "src": "Vietnam"
+  },
+  "us-minor-outlying-islands": {
+    "lat": -0.02,
+    "lon": -176.3,
+    "name": "US Minor Outlying Islands",
+    "src": "hardcoded"
+  }
+}

data/country_scripts.json

@@ -0,0 +1 @@
+{"alaska":["latin"],"albania":["latin"],"american-samoa":["latin"],"india":["latin","devanagari"],"andorra":["latin"],"argentina":["latin"],"russia":["latin","cyrillic"],"australia":["latin"],"austria":["latin"],"azores":["latin"],"spain":["latin"],"bangladesh":["latin","bengali"],"belarus":["latin","cyrillic"],"belgium":["latin"],"bermuda":["latin"],"bhutan":["latin"],"bolivia":["latin"],"botswana":["latin"],"brazil":["latin"],"bulgaria":["latin","cyrillic"],"cambodia":["latin","khmer"],"canada":["latin"],"chile":["latin"],"colombia":["latin"],"france":["latin"],"costa-rica":["latin"],"croatia":["latin"],"curacao":["latin"],"czechia":["latin"],"denmark":["latin"],"dominican-republic":["latin"],"ecuador":["latin"],"united-kingdom":["latin"],"estonia":["latin"],"eswatini":["latin"],"faroe-islands":["latin"],"finland":["latin"],"germany":["latin"],"ghana":["latin"],"gibraltar":["latin"],"greece":["latin","greek"],"greenland":["latin"],"guatemala":["latin"],"hawaii":["latin"],"hong-kong":["latin","cjk"],"hungary":["latin"],"iceland":["latin"],"ireland":["latin"],"isle-of-man":["latin"],"israel-west-bank":["latin","hebrew"],"italy":["latin"],"japan":["latin","cjk"],"jersey":["latin"],"jordan":["latin","arabic"],"indonesia":["latin"],"kazakhstan":["latin","cyrillic"],"kyrgyzstan":["latin","cyrillic"],"kenya":["latin"],"laos":["latin","lao"],"latvia":["latin"],"lebanon":["latin","arabic"],"lesotho":["latin"],"liechtenstein":["latin"],"lithuania":["latin"],"luxembourg":["latin"],"madeira":["latin"],"malaysia":["latin"],"malta":["latin"],"mexico":["latin"],"monaco":["latin"],"mongolia":["latin","cyrillic"],"montenegro":["latin","cyrillic"],"namibia":["latin"],"nepal":["latin","devanagari"],"netherlands":["latin"],"new-zealand":["latin"],"nigeria":["latin"],"north-macedonia":["latin","cyrillic"],"norway":["latin"],"oman":["latin","arabic"],"pakistan":["latin"],"panama":["latin"],"peru":["latin"],"philippines":["latin"],"poland":["latin"],"portugal":["latin"],"puerto-rico":["latin"],"qatar":["latin","arabic"],"cyprus":["latin","greek"],"romania":["latin"],"rwanda":["latin"],"reunion":["latin"],"san-marino":["latin"],"senegal":["latin"],"serbia":["latin","cyrillic"],"singapore":["latin"],"slovakia":["latin"],"slovenia":["latin"],"south-africa":["latin"],"sri-lanka":["latin","sinhala"],"sweden":["latin"],"switzerland":["latin"],"sao-tome-and-principe":["latin"],"taiwan":["latin","cjk"],"thailand":["latin","thai"],"tunisia":["latin","arabic"],"turkey":["latin"],"us-virgin-islands":["latin"],"uganda":["latin"],"ukraine":["latin","cyrillic"],"united-arab-emirates":["latin","arabic"],"united-states":["latin"],"uruguay":["latin"],"vietnam":["latin"]}

data/index_fast.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e85b6c2e9cf17d7b0d087ee52766153bcb7424c4a940ce7d5a72592c62421935
+size 4879488

data/index_geo.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d36c01d8fa7969e27d31b14cf7a3a6729cbf8ef95e7611476523538d206d831
+size 7319168

data/index_pro.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7c329f262461377f4ed439f8a71d2d34b0cb61046b03d59b24e8f29b6360f66
+size 7319168

data/priors.json

@@ -0,0 +1 @@
+{"alaska":90,"albania":210,"american-samoa":30,"india":1215,"andorra":30,"argentina":1200,"russia":1650,"australia":1410,"austria":450,"azores":60,"spain":1362,"bangladesh":600,"belarus":6,"belgium":400,"bermuda":30,"bhutan":300,"bolivia":510,"botswana":420,"brazil":1350,"bulgaria":600,"cambodia":450,"canada":1200,"chile":840,"colombia":900,"france":1300,"costa-rica":300,"croatia":540,"curacao":60,"czechia":600,"denmark":450,"dominican-republic":150,"ecuador":600,"united-kingdom":1350,"estonia":300,"eswatini":150,"faroe-islands":90,"finland":600,"germany":1200,"ghana":450,"gibraltar":30,"greece":700,"greenland":3,"guatemala":300,"hawaii":150,"hong-kong":60,"hungary":510,"iceland":450,"ireland":600,"isle-of-man":45,"israel-west-bank":600,"italy":1150,"japan":1350,"jersey":15,"jordan":300,"indonesia":1790,"kazakhstan":300,"kyrgyzstan":720,"kenya":650,"laos":90,"latvia":300,"lebanon":45,"lesotho":150,"liechtenstein":45,"lithuania":300,"luxembourg":135,"madeira":45,"malaysia":900,"malta":60,"mexico":1200,"monaco":60,"mongolia":300,"montenegro":240,"namibia":360,"nepal":240,"netherlands":360,"new-zealand":750,"nigeria":750,"north-macedonia":240,"norway":600,"oman":600,"pakistan":30,"panama":300,"peru":1140,"philippines":1200,"poland":600,"portugal":540,"puerto-rico":120,"qatar":90,"cyprus":240,"romania":600,"rwanda":300,"reunion":60,"san-marino":60,"senegal":450,"serbia":450,"singapore":90,"slovakia":450,"slovenia":450,"south-africa":1200,"sri-lanka":300,"sweden":600,"switzerland":300,"sao-tome-and-principe":15,"taiwan":300,"thailand":1200,"tunisia":300,"turkey":750,"us-virgin-islands":90,"uganda":150,"ukraine":450,"united-arab-emirates":450,"united-states":1200,"uruguay":300,"vietnam":540}

data/script_names.json

@@ -0,0 +1 @@
+["latin", "cyrillic", "greek", "thai", "cjk", "arabic", "hebrew", "devanagari", "bengali", "sinhala", "lao", "khmer"]

data/script_text.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8a98b41c66636024e464c8795557d7c42559faf5f2b5526d996d876264573ef
+size 18560

data/text_geo.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12ca4f31d1a267ff6c2fd51cc86f3d90b5a56f2bafc283af30977b288807fc27
+size 175232

data/text_geo_countries.json

@@ -0,0 +1 @@
+["alaska", "albania", "american-samoa", "andorra", "argentina", "australia", "austria", "azores", "bangladesh", "belarus", "belgium", "bermuda", "bhutan", "bolivia", "botswana", "brazil", "bulgaria", "cambodia", "canada", "chile", "colombia", "costa-rica", "croatia", "curacao", "cyprus", "czechia", "denmark", "dominican-republic", "ecuador", "estonia", "eswatini", "faroe-islands", "finland", "france", "germany", "ghana", "gibraltar", "greece", "greenland", "guatemala", "hawaii", "hong-kong", "hungary", "iceland", "india", "indonesia", "ireland", "isle-of-man", "israel-west-bank", "italy", "japan", "jersey", "jordan", "kazakhstan", "kenya", "kyrgyzstan", "laos", "latvia", "lebanon", "lesotho", "liechtenstein", "lithuania", "luxembourg", "madeira", "malaysia", "malta", "mexico", "monaco", "mongolia", "montenegro", "namibia", "nepal", "netherlands", "new-zealand", "nigeria", "north-macedonia", "norway", "oman", "pakistan", "panama", "peru", "philippines", "poland", "portugal", "puerto-rico", "qatar", "reunion", "romania", "russia", "rwanda", "san-marino", "sao-tome-and-principe", "senegal", "serbia", "singapore", "slovakia", "slovenia", "south-africa", "spain", "sri-lanka", "sweden", "switzerland", "taiwan", "thailand", "tunisia", "turkey", "uganda", "ukraine", "united-arab-emirates", "united-kingdom", "united-states", "uruguay", "us-virgin-islands", "vietnam"]

guess.py

@@ -0,0 +1,207 @@
+"""Phase 2 — search + country vote + template reasoning. No LLM, fully offline.
+
+Pure logic given an index (N,512 fp32, L2-normed), meta rows, and centroids.
+The same module is imported by app.py (the Space) and eval/eval.py (the PC), so
+the served algorithm and the evaluated algorithm are byte-identical.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Config:
+    K: int = 15          # top matches per view
+    P: float = 8.0       # similarity sharpening exponent
+    ALPHA: float = 0.4   # large-guide bias correction (S_c /= max(count[c], MIN_COUNT)**ALPHA)
+    MIN_COUNT: int = 20  # floor on the per-country image count used for ALPHA normalization,
+                         # so tiny guides (5–9 imgs) don't get a huge score boost and beat
+                         # large countries on weak matches (the "India → mid-Pacific" bug)
+    PRIOR_BETA: float = 0.3  # strength of the game-location prior (S_c *= available[c]**BETA).
+                             # 0 disables the prior (filter still applies). Higher = trust the
+                             # "how many real locations exist in this country" signal more.
+    TEXT_WEIGHT: float = 0.25  # blend weight for the zero-shot TEXT branch (geo only):
+                              # final = (1-W)*image_retrieval + W*image↔country_text. 0 disables.
+    P_TEXT: float = 4.0       # sharpening exponent for zero-shot text sims
+    JITTER_DEG: float = 0.0
+    MAX_CLUES: int = 3
+    RUNNER_SENTENCE_RATIO: float = 0.5  # show runner-up note when its score >= 50% of winner
+
+
+# --- reasoning templates, keyed by confidence band; chosen deterministically ---
+ASSERTIVE = [
+    "Both views match features documented for {country} — {clue1} and {clue2}.{runner} Placing my guess in central {country}.",
+    "This is {country} for me: I'm seeing {clue1}, and {clue2} backs it up.{runner} Dropping my pin in central {country}.",
+    "Clear {country} signals here — {clue1} together with {clue2}.{runner} I'll guess central {country}.",
+    "Confident on {country}: {clue1} and {clue2} both line up.{runner} Going central {country}.",
+]
+HEDGED = [
+    "This looks most like {country} to me — I matched {clue1}, though I also saw similarities to {runner_c}. Going with {country}.",
+    "Leaning {country}: {clue1} points that way, but {runner_c} crossed my mind too. I'll commit to {country}.",
+    "Probably {country} — {clue1} is the strongest hint, with {runner_c} as a maybe. Guessing {country}.",
+    "My read is {country} based on {clue1}, even if {runner_c} isn't far off. Placing it in {country}.",
+]
+UNCERTAIN = [
+    "Tough one. Weak matches all around, but {clue1} nudges me toward {country}, so that's my guess.",
+    "Not much to go on here — {clue1} is the only real hint, pointing at {country}. Rolling with it.",
+    "Low confidence on this. {clue1} loosely suggests {country}, so I'll take the shot.",
+    "Hard to read. {clue1} is faint, but it leans {country} — guessing there.",
+]
+
+
+def _pick(variants, seed_text):
+    return variants[abs(hash(seed_text)) % len(variants)]
+
+
+def _distinct_clues(matches, k):
+    """Up to k distinct clue texts, ordered by sim desc."""
+    out, seen = [], set()
+    for m in sorted(matches, key=lambda x: -x["sim"]):
+        c = m["clue"]
+        if c not in seen:
+            seen.add(c)
+            out.append(m)
+        if len(out) >= k:
+            break
+    return out
+
+
+def build_reasoning(country_name, confidence, winner_matches, runner_name, runner_matches, cfg):
+    clues = _distinct_clues(winner_matches, cfg.MAX_CLUES)
+    clue1 = clues[0]["clue"] if clues else "a few subtle details"
+    clue2 = clues[1]["clue"] if len(clues) > 1 else clue1
+    seed = "|".join(c["clue"] for c in clues) + country_name
+
+    if confidence >= 0.55:
+        runner = ""
+        if runner_name and runner_matches:
+            runner = f" I also weighed {runner_matches[0]['country_name']}, but those matches were weaker."
+        return _pick(ASSERTIVE, seed).format(
+            country=country_name, clue1=clue1.lower(), clue2=clue2.lower(), runner=runner)
+    if confidence >= 0.35:
+        runner_c = runner_matches[0]["country_name"] if runner_matches else "a neighbour"
+        return _pick(HEDGED, seed).format(country=country_name, clue1=clue1.lower(), runner_c=runner_c)
+    return _pick(UNCERTAIN, seed).format(country=country_name, clue1=clue1.lower())
+
+
+def guess(embs, index, rows, centroids, count, cfg=Config(), priors=None,
+          text_vecs=None, text_countries=None):
+    """embs: list of (D,) float32 L2-normed view embeddings (1+; e.g. 5 frames around
+    the spot + a downward car view). Returns the response dict.
+
+    priors: optional {slug: available_location_count}. When given, the bot can ONLY
+    guess countries present here (those the game actually has locations for) and
+    weights each by available_count**PRIOR_BETA.
+
+    text_vecs/(text_countries): optional (C,D) L2-normed country text embeddings and
+    their aligned slugs (StreetCLIP zero-shot). When given, the final score blends
+    image retrieval with image↔country-text similarity (cfg.TEXT_WEIGHT).
+    """
+    if not isinstance(embs, (list, tuple)):
+        embs = [embs]
+    matches = {}  # index row -> {sim, ...meta}
+    for e in embs:
+        sims = index @ e
+        top = np.argpartition(-sims, cfg.K)[: cfg.K] if len(sims) > cfg.K else np.arange(len(sims))
+        for idx in top:
+            s = float(sims[idx])
+            # if a row appears in both views, keep the larger sim but it still counts once here;
+            # union semantics with double-contribution handled by summing weights per view below
+            prev = matches.get(idx)
+            if prev is None:
+                r = rows[idx]
+                matches[idx] = {"sim": s, "country": r["country"],
+                                "country_name": r["country_name"], "clue": r["clue"],
+                                "page": r["page"], "_w": max(s, 0.0) ** cfg.P}
+            else:
+                # second view also matched this row: add its weight (intended double vote)
+                prev["_w"] += max(s, 0.0) ** cfg.P
+                prev["sim"] = max(prev["sim"], s)
+
+    # country scores
+    scores, by_country = {}, {}
+    for m in matches.values():
+        c = m["country"]
+        if priors is not None and priors.get(c, 0) <= 0:
+            continue  # country has no game locations → the bot must never guess it
+        scores[c] = scores.get(c, 0.0) + m["_w"]
+        by_country.setdefault(c, []).append(m)
+    for c in scores:
+        scores[c] /= (max(count.get(c, 1), cfg.MIN_COUNT) ** cfg.ALPHA)
+        if priors is not None:
+            scores[c] *= priors[c] ** cfg.PRIOR_BETA
+
+    if not scores:
+        # None of the matched countries are in the game's pool — fall back to the
+        # most location-rich country so we still return a valid, in-pool guess.
+        winner = max(priors, key=priors.get) if priors else rows[0]["country"]
+        cen = centroids[winner]
+        return {
+            "lat": cen["lat"], "lon": cen["lon"],
+            "country": winner, "country_name": cen["name"],
+            "confidence": 0.0, "runner_up": None,
+            "reasoning": "Couldn't match these views to anywhere I know — taking a blind guess.",
+            "clues": [],
+        }
+
+    # --- zero-shot TEXT branch (geo): blend image↔country-text with retrieval ---
+    if text_vecs is not None and text_countries is not None and cfg.TEXT_WEIGHT > 0:
+        sims_t = np.max(np.stack([text_vecs @ e for e in embs]), axis=0)  # best view per country
+        zs = {}
+        for i, c in enumerate(text_countries):
+            if priors is not None and priors.get(c, 0) <= 0:
+                continue
+            s = max(float(sims_t[i]), 0.0) ** cfg.P_TEXT
+            if priors is not None:
+                s *= priors[c] ** cfg.PRIOR_BETA
+            zs[c] = s
+        rsum = sum(scores.values()) or 1.0
+        zsum = sum(zs.values()) or 1.0
+        W = cfg.TEXT_WEIGHT
+        final = {
+            c: (1 - W) * (scores.get(c, 0.0) / rsum) + W * (zs.get(c, 0.0) / zsum)
+            for c in set(scores) | set(zs)
+        }
+    else:
+        final = scores
+
+    ranked = sorted(final.items(), key=lambda kv: -kv[1])
+    winner, win_score = ranked[0]
+    total = sum(final.values()) or 1.0
+    confidence = win_score / total
+    runner = ranked[1][0] if len(ranked) > 1 else None
+    runner_score = ranked[1][1] if len(ranked) > 1 else 0.0
+
+    win_matches = sorted(by_country.get(winner, []), key=lambda x: -x["sim"])
+    runner_matches = sorted(by_country.get(runner, []), key=lambda x: -x["sim"]) if runner else []
+
+    cen = centroids[winner]
+    # The ratio gate only governs the optional extra runner-up SENTENCE in the
+    # assertive band; the hedged band always names the actual runner-up.
+    show_runner = bool(runner) and runner_score >= cfg.RUNNER_SENTENCE_RATIO * win_score
+    if confidence >= 0.55:
+        reasoning = build_reasoning(cen["name"], confidence, win_matches,
+                                    runner if show_runner else None,
+                                    runner_matches if show_runner else [], cfg)
+    else:
+        reasoning = build_reasoning(cen["name"], confidence, win_matches,
+                                    runner, runner_matches, cfg)
+
+    clue_list = []
+    for m in _distinct_clues(win_matches, cfg.MAX_CLUES):
+        clue_list.append({"text": m["clue"], "country": m["country"],
+                          "page": m["page"], "sim": round(m["sim"], 3)})
+    if runner_matches:
+        m = runner_matches[0]
+        clue_list.append({"text": m["clue"], "country": m["country"],
+                          "page": m["page"], "sim": round(m["sim"], 3)})
+
+    return {
+        "lat": cen["lat"], "lon": cen["lon"],
+        "country": winner, "country_name": cen["name"],
+        "confidence": round(confidence, 3),
+        "runner_up": runner,
+        "reasoning": reasoning,
+        "clues": clue_list,
+    }

region.py

@@ -0,0 +1,56 @@
+"""Region kNN locator (Nomad-style, but for one country's scraped Street View).
+
+A region model holds N reference embeddings + their exact lat/lng. Inference:
+embed the round's frames → cosine-nearest reference across ALL frames → predict
+that reference's coordinates. Best for in-country precision (e.g. the Serbia model
+guessing where in Serbia a panorama is), not country classification.
+"""
+import numpy as np
+
+
+def load_region(path):
+    """Load a region index .npz → (ref_emb f32 normalised, lat, lng)."""
+    z = np.load(path, allow_pickle=True)
+    emb = z["emb"].astype(np.float32)
+    emb /= np.linalg.norm(emb, axis=1, keepdims=True) + 1e-8
+    return emb, z["lat"].astype(np.float64), z["lng"].astype(np.float64)
+
+
+def predict(embs, ref_emb, ref_lat, ref_lng, country_slug, country_name, k=5):
+    """embs: list of (D,) query-frame embeddings. Returns a scoreable guess dict
+    (same shape the bot/guess.py emits): predicted lat/lon from the nearest
+    reference image, confidence from cosine similarity."""
+    Q = np.stack([e / (np.linalg.norm(e) + 1e-8) for e in embs])  # (F, D)
+    sims = Q @ ref_emb.T                                          # (F, N)
+    fi, ni = np.unravel_index(int(np.argmax(sims)), sims.shape)
+    best = float(sims[fi, ni])
+
+    # Top-k across all frames → geo-medoid (robust to a single odd neighbour).
+    flat = sims.reshape(-1)
+    kk = min(k, flat.shape[0])
+    top = np.argpartition(-flat, kk - 1)[:kk]
+    cols = (top % ref_emb.shape[0])
+    cla, cln = ref_lat[cols], ref_lng[cols]
+    R = 6371.0088; p = np.pi / 180.0
+    dsum = np.empty(len(cols))
+    for i in range(len(cols)):
+        a = (np.sin((cla - cla[i]) * p / 2) ** 2
+             + np.cos(cla[i] * p) * np.cos(cla * p) * np.sin((cln - cln[i]) * p / 2) ** 2)
+        dsum[i] = (2 * R * np.arcsin(np.sqrt(np.clip(a, 0, 1)))).sum()
+    m = int(dsum.argmin())
+    lat, lon = float(cla[m]), float(cln[m])
+
+    conf = round(max(0.0, min(1.0, best)), 3)
+    return {
+        "country": country_slug,
+        "country_name": country_name,
+        "lat": lat,
+        "lon": lon,
+        "confidence": conf,
+        "runner_up": None,
+        "runner_up_conf": None,
+        "script": None,
+        "reasoning": f"Matched the closest of {ref_emb.shape[0]} {country_name} street views "
+                     f"(similarity {conf}).",
+        "clues": [],
+    }

requirements.txt

@@ -0,0 +1,8 @@
+# torch CPU is installed separately in the Dockerfile (pinned to the CPU index).
+transformers==5.11.0
+huggingface_hub
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pillow==11.1.0
+numpy==2.2.1
+python-multipart==0.0.20

shared/embedder.py

@@ -0,0 +1,33 @@
+"""The ONE embedder. Imported by both the indexer (PC) and the server (Space).
+
+Any divergence between index-time and serve-time preprocessing silently
+destroys retrieval accuracy, so there must be exactly one implementation.
+Vision-only: the server never needs the text tower.
+"""
+
+import numpy as np
+import torch
+from PIL import Image
+
+from transformers import CLIPVisionModelWithProjection, CLIPImageProcessor
+
+try:
+    from .version import MODEL_ID
+except ImportError:  # allow running as a loose script
+    from version import MODEL_ID
+
+
+class Embedder:
+    def __init__(self, model_id: str = MODEL_ID):
+        self.model_id = model_id
+        self.proc = CLIPImageProcessor.from_pretrained(model_id)
+        self.model = CLIPVisionModelWithProjection.from_pretrained(model_id).eval()
+
+    @torch.no_grad()
+    def embed(self, images: list[Image.Image]) -> np.ndarray:
+        """Return (B, 512) float32, L2-normalized rows. Input PIL images (any mode)."""
+        rgb = [im.convert("RGB") for im in images]
+        inputs = self.proc(images=rgb, return_tensors="pt")
+        emb = self.model(**inputs).image_embeds
+        emb = emb / emb.norm(dim=-1, keepdim=True)
+        return emb.float().cpu().numpy()

shared/version.py

@@ -0,0 +1,160 @@
+"""Single source of truth for model + index versioning.
+
+The indexer (PC) and the server (HF Space) both import these constants.
+The server asserts that meta.json carries matching values before it starts,
+so a stale index can never be served against a different model.
+"""
+
+# The indexer (build_index.py) builds THIS model's index (currently the "geo" index).
+MODEL_ID = "geolocal/StreetCLIP"
+INDEX_VERSION = "v3"
+
+# The Space serves multiple switchable models. Each has its own baked weights and
+# its own index/meta files in data/. Switch per request via /guess?model=<key>.
+MODELS = {
+    "fast": {
+        "model_id": "openai/clip-vit-base-patch32",
+        "index_version": "v1",
+        "index_file": "index_fast.npy",
+        "meta_file": "meta_fast.json",
+        "label": "Lite — ViT-B/32 (fast, less accurate)",
+    },
+    "pro": {
+        "model_id": "openai/clip-vit-large-patch14",
+        "index_version": "v2",
+        "index_file": "index_pro.npy",
+        "meta_file": "meta_pro.json",
+        "label": "Pro — ViT-L/14 (slower, more accurate)",
+    },
+    "geo": {
+        "model_id": "geolocal/StreetCLIP",
+        "index_version": "v3",
+        "index_file": "index_geo.npy",
+        "meta_file": "meta_geo.json",
+        "label": "Geo — StreetCLIP image retrieval only",
+    },
+    "geoplus": {
+        "model_id": "geolocal/StreetCLIP",
+        "index_version": "v3",
+        "index_file": "index_geo.npy",
+        "meta_file": "meta_geo.json",
+        "text_file": "text_geo.npy",
+        "text_countries_file": "text_geo_countries.json",
+        "label": "Geo+ — StreetCLIP + clue-text",
+    },
+    "atlas": {
+        "model_id": "geolocal/StreetCLIP",
+        "head_file": "atlas_head.npz",
+        "label": "Atlas — learned classifier (best)",
+    },
+    "serbia": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "serbia_index.npz",
+        "country_slug": "serbia",
+        "country_name": "Serbia",
+        "label": "Serbia — pinpoint locator (Serbia map only)",
+    },
+    "krajina": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "krajina_index.npz",
+        "country_slug": "krajina",
+        "country_name": "Krajina",
+        "label": "Krajina — pinpoint locator (Serbian Krajina map only)",
+    },
+    "usa": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "usa_index.npz",
+        "country_slug": "usa",
+        "country_name": "USA",
+        "map_id": "69c14929fc130ff0dfb0b916",
+        "label": "USA — pinpoint locator (USA map only)",
+    },
+    "canada": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "canada_index.npz",
+        "country_slug": "canada",
+        "country_name": "Canada",
+        "map_id": "69c13f8a66d5a179c340dd12",
+        "label": "Canada — pinpoint locator (Canada map only)",
+    },
+    "brazil": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "brazil_index.npz",
+        "country_slug": "brazil",
+        "country_name": "Brazil",
+        "map_id": "69c13f7066d5a179c340ac38",
+        "label": "Brazil — pinpoint locator (Brazil map only)",
+    },
+    "argentina": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "argentina_index.npz",
+        "country_slug": "argentina",
+        "country_name": "Argentina",
+        "map_id": "69c13c6466d5a179c33f9e16",
+        "label": "Argentina — pinpoint locator (Argentina map only)",
+    },
+    "russia": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "russia_index.npz",
+        "country_slug": "russia",
+        "country_name": "Russia",
+        "map_id": "69c1457b047406872f3c80f4",
+        "label": "Russia — pinpoint locator (Russia map only)",
+    },
+    "indonesia": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "indonesia_index.npz",
+        "country_slug": "indonesia",
+        "country_name": "Indonesia",
+        "map_id": "69c141f7200aba567e5352a8",
+        "label": "Indonesia — pinpoint locator (Indonesia map only)",
+    },
+    "peru": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "peru_index.npz",
+        "country_slug": "peru",
+        "country_name": "Peru",
+        "map_id": "69c144a7047406872f3be463",
+        "label": "Peru — pinpoint locator (Peru map only)",
+    },
+    "italy": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "italy_index.npz",
+        "country_slug": "italy",
+        "country_name": "Italy",
+        "map_id": "69c14219200aba567e538c4c",
+        "label": "Italy — pinpoint locator (Italy map only)",
+    },
+    "malaysia": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "malaysia_index.npz",
+        "country_slug": "malaysia",
+        "country_name": "Malaysia",
+        "map_id": "69c14385047406872f3af85c",
+        "label": "Malaysia — pinpoint locator (Malaysia map only)",
+    },
+    "colombia": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "colombia_index.npz",
+        "country_slug": "colombia",
+        "country_name": "Colombia",
+        "label": "Colombia — pinpoint locator (Colombia map only)",
+    },
+    "chile": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "chile_index.npz",
+        "country_slug": "chile",
+        "country_name": "Chile",
+        "map_id": "69c140b8200aba567e525880",
+        "label": "Chile — pinpoint locator (Chile map only)",
+    },
+    "new-zealand": {
+        "model_id": "geolocal/StreetCLIP",
+        "region_file": "new-zealand_index.npz",
+        "country_slug": "new-zealand",
+        "country_name": "New Zealand",
+        "map_id": "69c14422047406872f3b6e4f",
+        "label": "New Zealand — pinpoint locator (New Zealand map only)",
+    },
+}
+DEFAULT_MODEL = "atlas"