Findakin

Find a kin for every spectrum.

Findakin answers population questions about collections of astronomical spectra: which look alike, what structure they form, which stand out, which changed in time, and which representation (encoder) is the most physical. It is a local Python library built on spectro-kernel (one spectrum → one vector) and LanceDB (an embedded, versioned, columnar store with a vector index). No server, no account: your spectra stay on your disk.

Status: 0.1 alpha, API may still change. Findakin started as a hosted web application (FastAPI + MongoDB + Qdrant + React, retired in October 2026) and was rebuilt as a local-first library. Landing page: findakin.lelain.net.

spectro-kernel  = algorithms on ONE spectrum   (embeddings, I/O, lines, RV, reduction…)
Findakin        = questions on MANY spectra    (index, neighbours, clusters, anomalies,
                                                trajectories, encoder benchmarks)

Install

pip install findakin                 # core: store, ingestion, kernel recipes, k-NN
pip install "findakin[analysis]"     # + UMAP projection, HDBSCAN clustering
pip install "findakin[vo]"           # + SSAP / Virtual Observatory connectors
pip install "findakin[encoders]"     # + local PyTorch encoders (spectro-kernel embed_pretrained)

Python ≥ 3.11.

Quick start

from findakin import Store

st = Store.open("~/findakin/store")                 # a directory; created if missing

# 1. ingest — FITS (BeSS / ISIS / specINTI / Demetra dialects), CSV, JSON, TXT.
#    Spectra are deduplicated by content; metadata (object, time, instrument,
#    observer, site, resolution, coverage) is extracted from the headers.
report = st.ingest_folder("~/spectra/alphadra", source="staros", tags=["campaign:alphadra"])
print(report)                                       # 1012 files → 987 added, 25 duplicates, 0 errors

# 2. embed — any spectro-kernel strategy; several encoders coexist for the same spectra
enc = st.embed(strategy="dct", dim=256, norm_method="z_score")   # → 'dct:v1:256:nogrid:z_score'
enc_ll = st.embed(strategy="log_lambda", dim=256)                 # Doppler-robust recipe
# tip: with min_max the continuum term dominates the vector and every pair scores ≈ 0.99;
# z_score (zero mean) or continuum_subtracted let the lines drive the similarity.

# 3. ask
st.neighbours("~/spectra/new_alfdra.fits", k=10, encoder=enc)          # k-NN by file…
st.neighbours(some_id, k=10, encoder=enc, where="observer = 'mlelain'")  # …or by id, filtered
ids, X = st.vectors(enc, where="series_id = 'alf dra'")                 # numpy matrix for analysis

from findakin.analysis import cluster_embeddings, detect_anomalies, project_embeddings
labels = cluster_embeddings(X, method="hdbscan")
outliers = detect_anomalies(X, method="lof", contamination=0.02)
xy = project_embeddings(X, method="umap")

Same verbs on the command line:

findakin ingest ~/spectra/alphadra --source staros --tag campaign:alphadra
findakin embed --strategy dct --dim 256
findakin search ~/spectra/new_alfdra.fits -k 10
findakin info

What is in the store

A LanceDB directory, versioned, rebuildable from your files:

series_id groups spectra that form a trajectory in time: an object followed over epochs (default), a night of sky spectra (series_from="night", e.g. aurorae), or a folder.

Roadmap (short)

Phase 0 — store, ingestion, kernel encoders, k-NN, CLI ✅ · Phase 1 — common λ grids (inter-instrument alignment), flux__<grid> tables, vector indexes · Phase 2 — named populations, clusters / anomalies / projections stored as results, trajectory anomalies, Plotly notebook helpers · Phase 3 — learned encoders registry, encoder benchmark with an instrument-leakage score · Phase 4 — findakin-mcp over the store · Phase 5 — thin HTTP façade for STAROS / SpecRelay.

Development

uv venv .venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest -q
ruff check src tests

The landing page lives in website/ (Vite + React, deployed separately).

License

MIT — © 2026 Matthieu Le Lain.