Add files using upload-large-folder tool

SEMANTIC_NEIGHBORS.md

@@ -0,0 +1,69 @@
+# KeyboardRage semantic neighbors
+
+This adds original-embedding semantic-neighbor inspection to `galaxy_fly_three.html`.
+
+Note: I first prototyped the UI on `galaxy.html`, but the intended primary view is the Three.js fly-through view at:
+
+```text
+http://localhost:8888/galaxy/3D_galaxy/galaxy_fly_three.html
+```
+
+Important distinction:
+- The 3D galaxy coordinates (`x/y/z`) are only the visual UMAP projection.
+- Semantic neighbors are queried from original Granite definition embeddings.
+- FAISS HNSW is only used for candidate retrieval.
+- Final ranking/scores are exact cosine similarities against normalized float32 embeddings.
+
+## One-time index build
+
+From this directory:
+
+```bash
+../venv/bin/python build_semantic_index.py --resume
+```
+
+Outputs:
+- `semantic_embeddings.f32.npy`
+- `semantic_faiss_hnsw.index`
+- `semantic_index_meta.json`
+
+The embeddings file is large because it keeps float32 vectors for exact reranking.
+For ~2.84M rows x 384 dims, expect about 4.1 GiB for the `.npy` plus the FAISS HNSW index.
+
+## Run the backend
+
+```bash
+./launch_semantic_neighbors.sh
+```
+
+Equivalent:
+
+```bash
+../venv/bin/uvicorn semantic_neighbors_server:app --host 127.0.0.1 --port 8703
+```
+
+## Run the galaxy
+
+From the project root:
+
+```bash
+cd /home/ubu/Desktop/keyboardrage
+python3 -m http.server 8888
+```
+
+Open:
+
+```text
+http://localhost:8888/galaxy/3D_galaxy/galaxy_fly_three.html
+```
+
+Click `Inspect semantic neighbors: off` to enable the panel. Then click a point.
+
+Controls:
+- `K`: number of neighbors returned.
+- `filter`: all / same language / cross-language.
+- `lines`: show/hide 3D lines from selected point to semantic neighbors.
+- `table`: show/hide the Atlas-style neighbor table.
+- clicking a table row focuses that neighbor and queries its neighbors.
+
+If the backend/index is not ready, the browser panel shows the exact command to start the server or build the index.

launch_semantic_neighbors.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+exec ../venv/bin/uvicorn semantic_neighbors_server:app --host 127.0.0.1 --port 8703

neighbor_meta_armenian_western.json

@@ -0,0 +1,11 @@
+{
+  "language": "armenian_western",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 437,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_bosnian.json

@@ -0,0 +1,11 @@
+{
+  "language": "bosnian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 2905,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_catalan.json

@@ -0,0 +1,11 @@
+{
+  "language": "catalan",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 997,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_chinese_traditional.json

@@ -0,0 +1,11 @@
+{
+  "language": "chinese_traditional",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 42294,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:11Z"
+}

neighbor_meta_dutch.json

@@ -0,0 +1,11 @@
+{
+  "language": "dutch",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 3303,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_english.json

@@ -0,0 +1,11 @@
+{
+  "language": "english",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 352781,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:58Z"
+}

neighbor_meta_esperanto_h_sistemo.json

@@ -0,0 +1,11 @@
+{
+  "language": "esperanto_h_sistemo",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 15460,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:09Z"
+}

neighbor_meta_euskera.json

@@ -0,0 +1,11 @@
+{
+  "language": "euskera",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 145,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_finnish.json

@@ -0,0 +1,11 @@
+{
+  "language": "finnish",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 9975,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:09Z"
+}

neighbor_meta_french.json

@@ -0,0 +1,11 @@
+{
+  "language": "french",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 302443,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:43Z"
+}

neighbor_meta_friulian.json

@@ -0,0 +1,11 @@
+{
+  "language": "friulian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 122,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_galician.json

@@ -0,0 +1,11 @@
+{
+  "language": "galician",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 188,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_georgian.json

@@ -0,0 +1,11 @@
+{
+  "language": "georgian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 176,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_greek.json

@@ -0,0 +1,11 @@
+{
+  "language": "greek",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 10543,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:09Z"
+}

neighbor_meta_hausa.json

@@ -0,0 +1,11 @@
+{
+  "language": "hausa",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 175,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_hawaiian.json

@@ -0,0 +1,11 @@
+{
+  "language": "hawaiian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 557,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_hebrew.json

@@ -0,0 +1,11 @@
+{
+  "language": "hebrew",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 2921,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_hungarian.json

@@ -0,0 +1,11 @@
+{
+  "language": "hungarian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 2480,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_icelandic.json

@@ -0,0 +1,11 @@
+{
+  "language": "icelandic",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 754,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_indonesian.json

@@ -0,0 +1,11 @@
+{
+  "language": "indonesian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 5635,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_italian.json

@@ -0,0 +1,11 @@
+{
+  "language": "italian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 231321,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:33Z"
+}

neighbor_meta_japanese_romaji.json

@@ -0,0 +1,11 @@
+{
+  "language": "japanese_romaji",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 799,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_kannada.json

@@ -0,0 +1,11 @@
+{
+  "language": "kannada",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 71,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_kazakh.json

@@ -0,0 +1,11 @@
+{
+  "language": "kazakh",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 728,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_khmer.json

@@ -0,0 +1,11 @@
+{
+  "language": "khmer",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 291,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_kyrgyz.json

@@ -0,0 +1,11 @@
+{
+  "language": "kyrgyz",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 412,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_lao.json

@@ -0,0 +1,11 @@
+{
+  "language": "lao",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 325,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_latin.json

@@ -0,0 +1,11 @@
+{
+  "language": "latin",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 360,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_lithuanian.json

@@ -0,0 +1,11 @@
+{
+  "language": "lithuanian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 1771,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_macedonian.json

@@ -0,0 +1,11 @@
+{
+  "language": "macedonian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 18976,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:10Z"
+}

neighbor_meta_maltese.json

@@ -0,0 +1,11 @@
+{
+  "language": "maltese",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 563,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_mongolian.json

@@ -0,0 +1,11 @@
+{
+  "language": "mongolian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 1298,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_oromo.json

@@ -0,0 +1,11 @@
+{
+  "language": "oromo",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 430,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_persian.json

@@ -0,0 +1,11 @@
+{
+  "language": "persian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 8695,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_santali.json

@@ -0,0 +1,11 @@
+{
+  "language": "santali",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 64,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_serbian.json

@@ -0,0 +1,11 @@
+{
+  "language": "serbian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 3022,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:08Z"
+}

neighbor_meta_sinhala.json

@@ -0,0 +1,11 @@
+{
+  "language": "sinhala",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 39,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_slovenian.json

@@ -0,0 +1,11 @@
+{
+  "language": "slovenian",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 1294,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_swahili.json

@@ -0,0 +1,11 @@
+{
+  "language": "swahili",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 713,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_swiss_german.json

@@ -0,0 +1,11 @@
+{
+  "language": "swiss_german",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 66,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_tatar_crimean_cyrillic.json

@@ -0,0 +1,11 @@
+{
+  "language": "tatar_crimean_cyrillic",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 108,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_telugu.json

@@ -0,0 +1,11 @@
+{
+  "language": "telugu",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 462,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_thai.json

@@ -0,0 +1,11 @@
+{
+  "language": "thai",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 12901,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:09Z"
+}

neighbor_meta_xhosa.json

@@ -0,0 +1,11 @@
+{
+  "language": "xhosa",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 1089,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:07Z"
+}

neighbor_meta_yiddish.json

@@ -0,0 +1,11 @@
+{
+  "language": "yiddish",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 139,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

neighbor_meta_zulu.json

@@ -0,0 +1,11 @@
+{
+  "language": "zulu",
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 101,
+  "dim": 384,
+  "top_k": 200,
+  "computation": "pytorch_gpu_per_language",
+  "global_total": 2250636,
+  "created_at": "2026-05-23T20:40:06Z"
+}

semantic_index_meta.json

@@ -0,0 +1,17 @@
+{
+  "model": "ibm-granite/granite-embedding-97m-multilingual-r2",
+  "metric": "cosine_similarity_via_normalized_inner_product",
+  "rows": 2250636,
+  "dim": 384,
+  "order": "sorted words_emb/*.json, skipping rows without embedding_3d; matches galaxy_data.bin and atlas_data.parquet",
+  "embeddings": "semantic_embeddings.f32.npy",
+  "faiss_index": "semantic_faiss_hnsw.index",
+  "faiss": {
+    "type": "IndexFlatIP",
+    "exact": true,
+    "candidate_search_only": false,
+    "final_scores": "exact cosine over normalized float32 embeddings",
+    "note": "Built for immediate testing after HNSW build was too hot/slow. Queries scan all vectors but ranking is exact."
+  },
+  "created_at": "2026-05-23T00:09:17Z"
+}

semantic_neighbors_server.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Local semantic-neighbor API for KeyboardRage Galaxy.
+
+Neighbors are fully precomputed. Global mode uses neighbor_ids.npy (all 2.25M).
+Per-language mode uses neighbor_ids_{lang}.npy (within-language top-200).
+
+Precompute with: ../venv/bin/python precompute_neighbors.py --per-language
+"""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Literal
+
+import duckdb
+import numpy as np
+import pyarrow.parquet as pq
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+
+HERE = Path(__file__).resolve().parent
+ATLAS_PARQUET = HERE.parent / "atlas" / "atlas_data.parquet"
+NEIGHBOR_IDS_PATH = HERE / "neighbor_ids.npy"
+NEIGHBOR_SCORES_PATH = HERE / "neighbor_scores.npy"
+NEIGHBOR_META_PATH = HERE / "neighbor_meta.json"
+EMBEDDINGS_PATH = HERE / "semantic_embeddings.f32.npy"
+FAISS_INDEX_PATH = HERE / "semantic_faiss_hnsw.index"
+INDEX_META_PATH = HERE / "semantic_index_meta.json"
+
+app = FastAPI(title="KeyboardRage Semantic Neighbors", version="3.0")
+app.add_middleware(
+    CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"],
+)
+
+# Cache: {language: (ids_mmap, scores_mmap, lang_index_mmap)}
+_per_lang_cache: dict[str, tuple[np.ndarray, np.ndarray, np.ndarray | None]] = {}
+_global_ids: np.ndarray | None = None
+_global_scores: np.ndarray | None = None
+_meta_table = None
+_meta_rows: int | None = None
+_con = duckdb.connect(database=":memory:")
+
+
+def _load_metadata_table():
+    global _meta_table, _meta_rows
+    if _meta_table is None:
+        if not ATLAS_PARQUET.exists():
+            raise RuntimeError(f"Missing {ATLAS_PARQUET}")
+        _meta_table = pq.read_table(
+            ATLAS_PARQUET, columns=["x", "y", "z", "word", "language", "definition"],
+        )
+        _meta_rows = _meta_table.num_rows
+    return _meta_table
+
+
+def _load_global():
+    global _global_ids, _global_scores
+    if _global_ids is None:
+        if not NEIGHBOR_IDS_PATH.exists():
+            raise RuntimeError(f"Missing {NEIGHBOR_IDS_PATH.name}")
+        _global_ids = np.load(NEIGHBOR_IDS_PATH, mmap_mode="r")
+        _global_scores = np.load(NEIGHBOR_SCORES_PATH, mmap_mode="r")
+    return _global_ids, _global_scores
+
+
+def _load_per_language(language: str):
+    if language in _per_lang_cache:
+        return _per_lang_cache[language]
+
+    ids_path = HERE / f"neighbor_ids_{language}.npy"
+    scores_path = HERE / f"neighbor_scores_{language}.npy"
+    index_path = HERE / f"lang_index_{language}.npy"
+
+    if not ids_path.exists():
+        # Fall back to global
+        return _load_global()[0], _load_global()[1], None
+
+    ids = np.load(ids_path, mmap_mode="r")
+    scores = np.load(scores_path, mmap_mode="r")
+    lang_index = np.load(index_path, mmap_mode="r") if index_path.exists() else None
+
+    _per_lang_cache[language] = (ids, scores, lang_index)
+    return ids, scores, lang_index
+
+
+def _row(i: int) -> dict:
+    table = _load_metadata_table()
+    if i < 0 or i >= table.num_rows:
+        raise IndexError(i)
+    batch = table.slice(i, 1).to_pydict()
+    return {
+        "id": i,
+        "word": batch["word"][0],
+        "language": batch["language"][0],
+        "definition": batch["definition"][0],
+        "x": float(batch["x"][0]),
+        "y": float(batch["y"][0]),
+        "z": float(batch["z"][0]),
+    }
+
+
+def _rows(ids: list[int]) -> list[dict]:
+    return [_row(i) for i in ids]
+
+
+def _projected_distance(a: dict, b: dict) -> float:
+    dx = float(a["x"]) - float(b["x"])
+    dy = float(a["y"]) - float(b["y"])
+    dz = float(a["z"]) - float(b["z"])
+    return math.sqrt(dx * dx + dy * dy + dz * dz)
+
+
+@app.get("/health")
+def health():
+    status = {
+        "atlas_parquet": ATLAS_PARQUET.exists(),
+        "embeddings": EMBEDDINGS_PATH.exists(),
+        "precomputed_global": NEIGHBOR_IDS_PATH.exists(),
+    }
+    if ATLAS_PARQUET.exists():
+        status["rows"] = pq.ParquetFile(ATLAS_PARQUET).metadata.num_rows
+    if NEIGHBOR_META_PATH.exists():
+        status["neighbor_meta"] = json.loads(NEIGHBOR_META_PATH.read_text())
+    # List available per-language files
+    per_lang = sorted(
+        p.stem.replace("neighbor_ids_", "")
+        for p in HERE.glob("neighbor_ids_*.npy")
+    )
+    if per_lang:
+        status["per_language_available"] = per_lang
+    return status
+
+
+@app.get("/point/{point_id}")
+def point(point_id: int):
+    try:
+        return _row(point_id)
+    except Exception:
+        raise HTTPException(status_code=404, detail="point id out of range")
+
+
+@app.get("/neighbors/{point_id}")
+def neighbors(
+    point_id: int,
+    k: int = Query(10, ge=1, le=200),
+    language: str | None = Query(
+        None,
+        description="Restrict to within-language neighbors (e.g. 'french')",
+    ),
+    language_filter: Literal["all", "same", "cross"] = "all",
+    visible_languages: str | None = Query(None),
+):
+    query = _row(point_id)
+
+    if language:
+        # Per-language precomputed: map global_id → local_id
+        ids_arr, scores_arr, lang_index = _load_per_language(language)
+        if lang_index is not None:
+            local_id = int(lang_index[point_id])
+            if local_id < 0:
+                return {
+                    "query": query, "metric": "cosine",
+                    "space": "precomputed_per_language", "k": k,
+                    "language": language, "neighbors": [],
+                }
+            all_ids = np.asarray(ids_arr[local_id], dtype=np.int64)
+            all_scores = np.asarray(scores_arr[local_id], dtype=np.float32)
+        else:
+            # No per-language file, fall back to global with same-language filter
+            ids_arr, scores_arr = _load_global()
+            all_ids = np.asarray(ids_arr[point_id], dtype=np.int64)
+            all_scores = np.asarray(scores_arr[point_id], dtype=np.float32)
+            language_filter = "same"
+    else:
+        ids_arr, scores_arr = _load_global()
+        all_ids = np.asarray(ids_arr[point_id], dtype=np.int64)
+        all_scores = np.asarray(scores_arr[point_id], dtype=np.float32)
+
+    # Drop sentinels (0 = no more neighbors)
+    valid = all_ids >= 0
+    all_ids = all_ids[valid]
+    all_scores = all_scores[valid]
+
+    if all_ids.size == 0:
+        return {
+            "query": query, "metric": "cosine",
+            "space": "precomputed", "k": k, "neighbors": [],
+        }
+
+    # Parse visible-language filter
+    visible_set = None
+    if visible_languages:
+        visible_set = {p.strip() for p in visible_languages.split(",") if p.strip()}
+        if not visible_set:
+            visible_set = None
+
+    has_filter = language_filter != "all" or visible_set is not None
+    rows = _rows([int(i) for i in all_ids.tolist()])
+
+    eligible_scores: list[float] = []
+    eligible_rows: list[dict] = []
+
+    for idx, (cid, row) in enumerate(zip(all_ids.tolist(), rows)):
+        if visible_set is not None and row["language"] not in visible_set:
+            continue
+        if language_filter == "same" and row["language"] != query["language"]:
+            continue
+        if language_filter == "cross" and row["language"] == query["language"]:
+            continue
+        eligible_rows.append(row)
+        eligible_scores.append(float(all_scores[idx]))
+
+    if has_filter and eligible_scores:
+        order = sorted(range(len(eligible_scores)), key=lambda i: -eligible_scores[i])[:k]
+    else:
+        order = list(range(min(k, len(eligible_scores))))
+
+    out = []
+    for rank, pos in enumerate(order, start=1):
+        row = eligible_rows[pos]
+        sim = eligible_scores[pos]
+        out.append({
+            **row, "rank": rank,
+            "cosine_similarity": sim,
+            "cosine_distance": float(1.0 - sim),
+            "projected_distance_3d": _projected_distance(query, row),
+        })
+
+    return {
+        "query": query, "metric": "cosine",
+        "space": "precomputed_per_language" if language else "precomputed_global",
+        "k": k, "language_filter": language_filter,
+        "visible_languages": sorted(visible_set) if visible_set else None,
+        "candidates_examined": int(all_ids.size),
+        "neighbors": out,
+    }
+
+
+@app.get("/search")
+def search(
+    q: str = Query(..., min_length=1),
+    limit: int = Query(25, ge=1, le=200),
+    language: str | None = Query(None, description="Filter by language"),
+):
+    if not ATLAS_PARQUET.exists():
+        raise HTTPException(status_code=500, detail="atlas_data.parquet missing")
+    safe_q = q.replace("'", "''")
+    lang_clause = ""
+    if language:
+        safe_lang = language.replace("'", "''")
+        lang_clause = f"AND lower(language) = lower('{safe_lang}')"
+    sql = f"""
+      WITH t AS (
+        SELECT row_number() OVER () - 1 AS id, word, language, x, y, z, definition
+        FROM read_parquet('{ATLAS_PARQUET.as_posix()}')
+      )
+      SELECT id, word, language, x, y, z, definition
+      FROM t
+      WHERE (lower(word) = lower('{safe_q}') OR lower(word) LIKE '%' || lower('{safe_q}') || '%')
+        {lang_clause}
+      ORDER BY CASE WHEN lower(word) = lower('{safe_q}') THEN 0 ELSE 1 END, word
+      LIMIT {int(limit)}
+    """
+    rows = _con.execute(sql).fetchall()
+    cols = ["id", "word", "language", "x", "y", "z", "definition"]
+    return {"results": [dict(zip(cols, r)) for r in rows]}