spectro-kernel 0.1.2__tar.gz → 0.1.4__tar.gz

{spectro_kernel-0.1.2 → spectro_kernel-0.1.4}/CHANGELOG.md

@@ -6,6 +6,151 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-06-10
+
+### Fixed — Lick atomic equivalent-width formula (CRITICAL)
+
+`embed_lick_indices` was computing
+``EW = (λ_hi − λ_lo) × (1 − mean(F/Fc))`` for atomic indices instead of
+the canonical Worthey-1994 form ``EW = ∫(1 − F/Fc) dλ``. The two only
+agree when pixel edges fall exactly on the band limits — which never
+happens on real data — so every atomic Lick value produced by ≤ 0.1.3
+was systematically **inflated by ~1–2 Å**. The molecular-magnitude form
+was correct.
+
+Algorithm version bumped 1.0.0 → 2.0.0; any indexed Lick embedding from
+≤ 0.1.3 should be **re-computed**. Companion fix in ``_band_mean_flux``:
+the band mean now uses the actual covered pixel span (not the nominal
+``hi − lo``) and refuses bands less than half-covered by the spectrum.
+
+### Fixed — SSRF on `load_spectrum` / `load_spectrum_from_url` (CRITICAL)
+
+The MCP file-loading tools forwarded the user-supplied URL directly to
+``urllib.request.urlretrieve`` with no host validation, no redirect
+control, no timeout and no size cap. An attacker could fetch instance
+metadata (``http://169.254.169.254/latest/meta-data/iam/...``), scan the
+VPC interior, or stream a 10 GB file to exhaust the worker.
+
+New module ``spectro_mcp/url_safety.py`` gates every URL coming from
+MCP through:
+- scheme allowlist (``http``/``https`` only);
+- ``localhost`` and DNS-resolved IP validation (refuses loopback,
+  RFC1918, link-local, multicast, reserved, unspecified);
+- a no-redirect HTTP handler (a friendly upstream can't 302 to
+  ``169.254.169.254`` after the hostname guard passes);
+- 60-second timeout plus 256 MiB byte cap on downloads.
+
+### Fixed — Path traversal on the HTTP MCP server (HIGH)
+
+``load_spectrum(session_id, path)`` accepted any local filesystem path,
+including ``/etc/passwd`` and ``/proc/self/environ`` (which leaks
+``SPECTRO_MCP_API_KEY``, ``AWS_*``, ``SPECTRO_MCP_REDIS_URL``, …).
+
+Local paths are now refused when the new env var
+``SPECTRO_MCP_DENY_LOCAL_PATHS=1`` is set, and the ``--http`` entry
+point sets it automatically. ``--stdio`` mode (the local default) is
+unaffected — the user's own machine is trusted by definition.
+
+### Fixed — Pickle deserialisation from Redis (HIGH)
+
+``RedisSessionManager.get()`` called ``pickle.loads`` on whatever
+arbitrary bytes Redis returned. Any path that lets an attacker write to
+the Redis backing store (compromised Redis, MITM with no TLS, leaked
+``SPECTRO_MCP_REDIS_URL``) → arbitrary code execution on the next
+``get``.
+
+Payloads are now wrapped with an HMAC-SHA256 signature derived from
+``SPECTRO_MCP_SESSION_SECRET`` (env). Without that env var the server
+generates a one-shot random secret at boot (sessions don't survive a
+restart in that case — a clear stderr warning is emitted). Unsigned or
+mis-signed blobs raise ``ValueError`` before ``pickle.loads`` runs.
+
+### Fixed — MCP stdio corruption from boot-time stdout prints (HIGH)
+
+In stdio mode, stdout is the JSON-RPC wire to the agent. Two paths
+emitted bytes on stdout that corrupted the very first handshake:
+
+1. Algorithm discovery imported ``astroquery`` (Gaia DR4 banner, ~390 B)
+   and ``easyspec`` (version banner, ~30 B). FD-level writes that
+   ``contextlib.redirect_stdout`` doesn't catch.
+2. ``configure_logger`` attached the audit handler to ``sys.stdout``;
+   every tool call therefore emitted a JSON record on the wire.
+
+Fix: a new ``_silence_fd_stdout`` context manager in ``__main__``
+``dup2``'s FD 1 to FD 2 for the boot phase (catches even C-level
+writes), and the audit logger now targets ``sys.stderr``. HTTP mode is
+unchanged.
+
+### Hardened — Dockerfile non-root user (MED)
+
+Default container user was root. The Dockerfile now creates an
+unprivileged ``app`` (UID 10001) and drops to it before ``CMD``. Any
+future vulnerability that reaches the filesystem is confined to the
+app user's home.
+
+### Hardened — Discovery silent error swallow (LOW)
+
+``registry.ensure_discovered`` silently dropped any submodule that
+failed to import. The intent (gracefully skip algorithms whose optional
+extra is missing) is preserved, but a bug-induced import failure used
+to vanish without trace. Discovery now logs every dropped submodule
+via the ``spectro_kernel.registry`` logger.
+
+### Added
+
+- ``tests/unit/test_mcp_security.py`` — 15 new tests covering every
+  v0.1.4 finding (SSRF target families, path-traversal env-var gate,
+  HMAC roundtrip + tamper + wrong-key, RedisSessionManager round-trip
+  via fakeredis, ``_resolve_redis_secret`` env-vs-random behaviour).
+- 2 new Lick regression tests (``test_lick_atomic_ew_matches_worthey_integral``,
+  ``test_lick_band_mean_uses_actual_pixel_span``).
+
+### Migration notes
+
+- Re-index any vectors produced by ``embed_lick_indices`` ≤ 0.1.3
+  (values changed by 1–2 Å on atomic indices).
+- For Redis-backed deployments: set ``SPECTRO_MCP_SESSION_SECRET`` to
+  a stable 32-byte secret in the environment. Otherwise sessions don't
+  survive a restart.
+- For HTTP deployments where you want users to send local paths anyway
+  (uncommon), unset ``SPECTRO_MCP_DENY_LOCAL_PATHS`` explicitly.
+
+## [0.1.3] — 2026-06-09
+
+### Fixed — circular import that prevented `from spectro_kernel.embeddings import …`
+
+In 0.1.2, `spectro_kernel.algorithms.__init__` ran an eager submodule
+walk at import time. That walk imported every algorithm, including
+`embed_continuum_subtracted`, which itself did a top-level
+`from ...embeddings import VALID_NORM_METHODS, VALID_STRATEGIES,
+embed_flux`. But `embeddings` itself imports
+`spectro_kernel.algorithms._common` before defining `VALID_*` /
+`embed_flux` — so when an external consumer wrote
+`from spectro_kernel.embeddings import embed_flux` as its very first
+contact with the kernel, Python's import machinery saw a partially
+initialised module and raised `ImportError`.
+
+Reported by a downstream library whose service worker crashed
+deterministically on the same PyPI 0.1.2 wheel.
+
+The fix moves discovery into `registry.ensure_discovered()`, which was
+already the lazy entry point — every registry getter (`list_algorithms`,
+`get_algorithm`, `run_algorithm`, …) calls it before answering.
+Importing `spectro_kernel.algorithms` is now a true no-op, so pulling a
+helper out of `algorithms._common` from inside `embeddings` no longer
+triggers a transitive cycle. Discovery now silently skips any
+optional-extra algorithm whose dependency is missing, instead of
+breaking the entire import chain.
+
+Behaviour preservation: existing callers that go through the registry
+see the same catalogue at the same time (the first registry call
+populates it, exactly as before). The only change is **when** discovery
+runs — it's properly lazy now.
+
+Added 4 regression tests in `test_no_circular_imports.py` that run the
+exact cold-start imports the bug reporter hit, in fresh subprocesses,
+so a future re-introduction of the cycle is caught immediately by CI.
+
 ## [0.1.2] — 2026-06-05
 
 ### Added — embedding category (8 algorithms total)

{spectro_kernel-0.1.2 → spectro_kernel-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.1.2
+Version: 0.1.4
 Summary: A shared catalogue of astronomical spectroscopy algorithms, composable into reproducible pipelines, usable as a Python library, a CLI, or an MCP server.
 Project-URL: Homepage, https://github.com/matthieulel/spectro-kernel
 Project-URL: Documentation, https://matthieulel.github.io/spectro-kernel/

spectro_kernel-0.1.4/docs/notebooks/alpha-cyg-time-series.md

@@ -0,0 +1,155 @@
+# α Cyg — 124 amateur spectra of a pulsating supergiant
+
+**A second real-world walkthrough of `spectro-kernel`, complementary to the
+[α Dra binary case](alpha-dra-binary-period.md).** Deneb (α Cyg, A2 Ia) is
+not a binary — it's the **prototype of the α-Cygni variables**: a
+non-radial pulsating supergiant whose H-α profile is also shaped by an
+ionised stellar wind. Where α Dra gave a single clean orbital period, α
+Cyg exhibits low-amplitude, **multi-periodic, sometimes irregular**
+variability on timescales of weeks. This notebook applies the same kernel
+pipeline as the α Dra case and **honestly reports** what amateur data of a
+genuinely harder target can and can't deliver.
+
+The complete script is at
+[`playground/analyse_alpha_cyg.py`](https://github.com/matthieulel/spectro-kernel/blob/main/playground/analyse_alpha_cyg.py).
+
+## Dataset provenance
+
+The 124 FITS files come from an amateur monitoring campaign of Deneb run
+between **2020 and 2024** (~12 contributing observers, slit spectrographs
+typically R ≈ 5 000–20 000 centred on H-α). The data is **not bundled
+with this repository** — drop your own FITS into
+`playground/datas/alphacygni/` and the script picks them up automatically.
+
+> If you contributed spectra to or reuse spectra from a public archive,
+> please cite the relevant campaign. Personal observer attributions have
+> been omitted from this notebook — the kernel showcases the analysis
+> pipeline, not the source of any specific measurement.
+
+## The pipeline
+
+Identical to the α Dra one — same algorithms, same defaults:
+
+```python
+from spectro_kernel import WorkContext, run_algorithm
+from spectro_kernel.io import read_fits
+
+ctx = WorkContext(spectrum=read_fits(path))
+run_algorithm("snr_der", ctx)
+run_algorithm("normalize_polynomial", ctx, {"order": 3})
+run_algorithm("fit_gaussian_line", ctx,
+              {"line_center_angstrom": 6562.81, "window_angstrom": 30.0})
+# Embedding restricted to H-α ± 50 Å for similarity comparison
+region = ctx.copy()
+run_algorithm("extract_region", region,
+              {"wavelength_min": 6512.81, "wavelength_max": 6612.81})
+run_algorithm("embed_spectrum", region, {"dim": 128, "strategy": "dct"})
+```
+
+124/124 spectra pass the basic SNR/RV sanity filter — Deneb is bright
+enough that even modest amateur setups give usable spectra.
+
+## Result 1 — RV vs time
+
+Centroid of the H-α Gaussian fit, converted to radial velocity (km/s),
+median-subtracted:
+
+![α Cyg RV time series](../images/notebooks/alpha_cyg_rv_timeseries.png)
+
+The series shows **two main observing campaigns** (a dense 2023 cluster
+around MJD 60 100–60 250, and a 2024 cluster around MJD 60 400–60 550)
+plus a few isolated 2020 / 2023-summer points. Within each campaign, RV
+scatter is **~±20 km/s**, consistent with α Cyg-variable pulsation
+amplitudes documented in the literature. Between campaigns, there is a
+**systematic offset** (the 2024 mean RV sits ~15 km/s above the 2023 mean)
+that could be a real long-term modulation OR an instrument-mix effect
+between observers — the kernel can't tell those apart.
+
+## Result 2 — Periodogram (and an honest caveat)
+
+Lomb-Scargle on the (time, RV) pairs:
+
+![α Cyg periodogram](../images/notebooks/alpha_cyg_periodogram.png)
+
+The dominant peak sits at **~553 days**, but **this is largely a sampling
+artefact** rather than a stellar period: it corresponds to the spacing
+between the two observing campaigns. The genuine α Cyg-variable
+pulsations have published timescales of ~11–100 days; the periodogram
+shows enhanced power in that range too (the bumpy plateau between 30 and
+100 days) but no single sharp peak — exactly what's expected from a
+multi-periodic, semi-coherent pulsator observed at heterogeneous cadence.
+
+> **Take-away.** A periodogram on amateur data is a *measurement*, not a
+> *truth*. The kernel reports what's in the data without lying; turning
+> that into astrophysics requires a critical eye on the sampling. For α
+> Dra (single clean binary period, ~4 cycles densely sampled) the
+> periodogram nails it. For α Cyg (multi-periodic, unevenly sampled), the
+> answer is "yes there's variability on 10–100 day scales, no single
+> period dominates".
+
+## Result 3 — H-α profile gallery
+
+The H-α region of every spectrum, overlaid:
+
+![α Cyg H-α overlay](../images/notebooks/alpha_cyg_overlay.png)
+
+Most spectra share the same characteristic A-supergiant H-α absorption
+profile, with the small profile variations expected for α Cyg-variables.
+A handful of low-SNR observations and a few obvious mis-calibrations stand
+out — visible without any per-file labelling, just from the spread of the
+flux trace.
+
+## Result 4 — Embedding latent space
+
+Each H-α region is embedded to a 128-d vector via `embed_spectrum`
+(`strategy="dct"`); the 124 vectors are then PCA-projected to 2D, with
+each point coloured by its phase at the periodogram's best period:
+
+![α Cyg PCA latent space coloured by phase](../images/notebooks/alpha_cyg_pca_2d.png)
+
+There **is** a colour gradient (early phases at right, mid phases at
+centre, late phases scattered at top) but it's far less clean than the α
+Dra version — because the underlying period isn't really 553 days, it's a
+mix of shorter-scale pulsations and a sampling artefact. **The
+embedding's latent axes still capture the most variable directions of the
+dataset** — but with α Cyg those don't align with one single phase like
+they did with α Dra's clean orbit.
+
+## What you actually learn from this dataset
+
+- **Sub-day RV scatter of ~20 km/s** within each observing campaign,
+  consistent with low-amplitude pulsations of an A Ia supergiant.
+- **A long-term offset between 2023 and 2024 campaigns** that requires
+  inter-instrument cross-calibration to interpret astrophysically.
+- **No single dominant pulsation period** — α Cyg-variables are known to
+  be multi-periodic / quasi-periodic, and a 4-year amateur monitoring is
+  consistent with that.
+- **The kernel pipeline reports all of the above without any
+  Deneb-specific tuning** — same six algorithm calls as the α Dra binary
+  notebook, applied to 124 files instead of 240.
+
+## Reproducing this
+
+```bash
+cd playground
+python3.12 -m venv venv && source venv/bin/activate
+pip install -e "..[viz]" plotly kaleido
+# drop your own alphacyg_*.fits files in playground/datas/alphacygni/
+python analyse_alpha_cyg.py
+# → output/alpha_cyg_*.png + alpha_cyg_summary.csv
+```
+
+## Takeaway compared to α Dra
+
+| | α Dra (binary) | α Cyg (supergiant pulsator) |
+|---|---|---|
+| Underlying physics | single Keplerian orbit | multi-periodic pulsations + wind |
+| Expected RV signal | clean ~120 km/s sinusoid at 51 d | semi-coherent ~±20 km/s on 10–100 d |
+| Periodogram outcome | single sharp peak at 51.6 d | broad plateau + sampling-driven peak |
+| Phase-folded curve | clean asymmetric loop (eccentric orbit) | mostly noise at any candidate period |
+| Embedding latent space | PCA axis = orbital phase | PCA axis = mixed variability + outliers |
+
+These are the **right** behaviours given the underlying physics — the
+kernel doesn't try to force a periodicity on a star that doesn't have a
+clean one. The same pipeline tells two different stories from two
+different datasets, faithfully.

spectro_kernel-0.1.4/docs/notebooks/alpha-dra-binary-period.md

@@ -0,0 +1,210 @@
+# α Dra — recovering a binary period from 240 amateur spectra
+
+**A second real-world walkthrough of `spectro-kernel`, this time on a known
+spectroscopic binary.** Alpha Draconis (Thuban) has a published orbital
+period of **51.42 days** and a non-negligible eccentricity (e ≈ 0.42; see
+Bischoff et al. 2017, A&A). The dataset below — 240 H-α spectra collected
+by amateur observers between May 2022 and August 2023 — is enough to
+**independently recover the period to within 0.3 %** and **reveal the
+eccentric character of the orbit**.
+
+The full script is at
+[`playground/analyse_alpha_dra.py`](https://github.com/matthieulel/scal-kernel/blob/main/playground/analyse_alpha_dra.py).
+
+## Dataset provenance
+
+The 240 FITS files come from an amateur monitoring campaign of α Dra
+between **May 2022 and August 2023** (14-month baseline, ~10 contributing
+observers, slit spectrographs typically R ≈ 5 000 – 20 000 centred on
+H-α). The dense 2023 sub-campaign covers ~4 full binary orbits — enough
+for a clean periodogram.
+
+The data is **not bundled with this repository** — drop your own
+`alphadra_*.fits` files into `playground/datas/alphadra/` and the script
+picks them up automatically.
+
+> If you contributed spectra to or reuse spectra from a public archive,
+> please cite the relevant campaign. Personal observer attributions have
+> been omitted from this notebook — the kernel showcases the analysis
+> pipeline, not the source of any specific measurement.
+
+## The pipeline
+
+Identical to the α Cyg one — same algorithms, same defaults — except for
+two adaptations to the binary case:
+
+1. The Gaussian-fit window is **40 Å** (vs. 30 Å for α Cyg) because the
+   H-α line itself drifts by several Å across the orbit due to the
+   primary's Doppler motion.
+2. We record the **line CENTROID** (not just the equivalent width), and
+   convert wavelength shift → radial velocity:
+   `RV [km/s] = c × (λ_fit − λ_rest) / λ_rest`.
+
+```python
+from spectro_kernel import WorkContext, run_algorithm
+from spectro_kernel.io import read_fits
+
+ctx = WorkContext(spectrum=read_fits(path))
+run_algorithm("snr_der", ctx)
+run_algorithm("normalize_polynomial", ctx, {"order": 3})
+run_algorithm("fit_gaussian_line", ctx,
+              {"line_center_angstrom": 6562.81, "window_angstrom": 40.0})
+fit = next(iter(ctx.line_fits.values()))
+rv_kms = 299792.458 * (fit.line_center_angstrom - 6562.81) / 6562.81
+```
+
+That's the per-spectrum extraction. The periodogram and phase fold then
+operate on the **(time, RV)** sample set, agnostic to the kernel — they're
+just `astropy.timeseries.LombScargle` calls.
+
+## Result 1 — Radial velocity vs time
+
+After fitting all 240 spectra and dropping the bad-SNR / unphysical-RV
+outliers, the median-subtracted RV time series:
+
+![α Dra RV time series](../images/notebooks/alpha_dra_rv_timeseries.png)
+
+The 2022 epoch is sparse (a handful of points), but the 2023 campaign
+already shows **the binary signal by eye**: ~4 visible peaks corresponding
+to ~4 orbital cycles. Peak-to-peak amplitude ~120 km/s, which sets the
+order of magnitude of the binary motion.
+
+## Result 2 — Lomb-Scargle periodogram
+
+Run on the unevenly-sampled (time, RV) pairs, no pre-detrending other
+than median subtraction:
+
+![α Dra periodogram](../images/notebooks/alpha_dra_periodogram.png)
+
+A **single dominant peak at 51.59 days** towers above a noisy background.
+
+| Quantity | Our value | Literature (Bischoff+ 2017) | Relative error |
+|---|---|---|---|
+| Orbital period (days) | **51.59** | 51.42 | **0.33 %** |
+
+The smaller bump around 25-27 d is a harmonic — expected for an eccentric
+orbit (the asymmetric RV curve has power at the 2nd harmonic of the
+fundamental). The high-frequency noise around 1 day is the sampling
+cadence (1 spectrum per night).
+
+## Result 3 — Phase-folded RV curve
+
+Folding the 240 RV points at the best period:
+
+![α Dra phase folded](../images/notebooks/alpha_dra_phase_folded.png)
+
+**The folded curve is asymmetric** — not the gentle sinusoid you'd expect
+from a circular orbit. It shows a fast positive peak around phase 0.1
+(reaching ~+50 km/s), then a slow descent through phase 0.3 – 0.8 (around
+−15 km/s), then a slow rise back to zero. This is the canonical signature
+of an **eccentric Keplerian orbit** — the primary spends more time at
+apastron (slow tail) and zips through periastron (sharp peak).
+
+The literature value for α Dra is **e ≈ 0.42**, which would produce exactly
+this kind of shape. We didn't fit an explicit Kepler orbit (we could —
+`fit_keplerian_orbit` exists in the catalogue), but the *qualitative*
+asymmetry is unmistakable from the folded raw measurements.
+
+## Result 4 — The orbit is visible in the raw spectra
+
+Before talking about latent spaces, the most direct evidence the binary
+motion is in the data: bin the 240 spectra by orbital phase, average each
+bin, plot the means side-by-side around H-α.
+
+![α Dra H-α profile stacked by phase](../images/notebooks/alpha_dra_halpha_phase_stack.png)
+
+**The absorption notch slides left/right of the rest wavelength** (the
+black dotted line at 6562.81 Å) as the orbital phase advances:
+
+- Phase 0.5-0.67 (cyan): the line is **blueshifted** — the primary is moving toward us.
+- Phase 0.0-0.17 (red, bottom) and 0.17-0.33 (yellow): the line drifts **back through
+  the rest wavelength and into the red** — the primary's RV reverses through
+  periastron.
+
+You don't need an algorithm to see this; you just need 240 well-calibrated
+amateur spectra and a phase-binning. This is the *raw spectroscopic
+signature* of a spectroscopic binary.
+
+## Result 5 — The embedding latent space *is* the orbit
+
+Now the algorithmic claim: each of the 240 H-α regions is embedded to a
+128-d vector via `embed_spectrum(strategy="dct")`. **The Doppler shift we
+just saw by eye gets automatically encoded as the principal direction of
+the embedding cloud.** Plot it the simple way — the first principal
+component vs. orbital phase:
+
+![α Dra PC1 vs orbital phase](../images/notebooks/alpha_dra_pc1_vs_phase.png)
+
+The shape is unmistakable: PC1 follows a clear (asymmetric) cycle in
+phase, with the **same morphology** as the RV phase-fold from Result 3 —
+sharp positive peak at phase 0.1, slow descent to a plateau around
+phase 0.4-0.7, slow rise back. A pure sinusoid here would mean a
+circular orbit; this asymmetric shape echoes the eccentricity again.
+
+In other words, **PCA on the embedding cloud rediscovers the radial
+velocity**, with no input other than "flux → DCT → truncate → L2".
+
+For completeness, the 2D PCA scatter coloured by phase tells the same
+story in two dimensions:
+
+![α Dra PCA latent space coloured by phase](../images/notebooks/alpha_dra_pca_2d.png)
+
+A horizontal colour gradient (blue on the left for late phases, red on
+the right for early phases) shows that PC1 carries the phase axis. The
+2D plot is busier than the 1D PC1-vs-phase view above, but it confirms
+the structure isn't a fluke of one direction.
+
+We did not tell the embedding what to look for. We just gave it
+``flux → DCT → truncate → L2 normalise`` and let it run. The Doppler shift
+of H-α across the orbit ends up encoded in one direction of the latent
+space — which is exactly the property a similarity layer or a clustering
+algorithm needs to leverage.
+
+A small caveat: a handful of low-SNR / mis-fit spectra would otherwise
+dominate the leading PCs and hide the phase structure of the bulk. The
+plot above uses the inner 95 % of the embedding cloud (15 outliers
+dropped on a robust Euclidean-distance criterion). The dropped points
+are real — they correspond to spectra where the H-α profile fit fails or
+where the data quality is too poor — but their structure is independent
+of orbital phase, so removing them lets the phase signal become visible.
+
+For completeness, the pairwise cosine-similarity matrix re-ordered by
+phase tells the same story in a different form:
+
+![α Dra similarity by phase](../images/notebooks/alpha_dra_similarity_phase.png)
+
+(At 240 × 240 the per-cell labels are unreadable in this preview — the
+full-resolution version is in the script's output folder.) Spectra near
+the same orbital phase are slightly more similar to each other than to
+spectra at the opposite phase, which gives a faint block-diagonal pattern
+in the third decimal of the cosine similarity.
+
+## Reproducing this
+
+```bash
+cd playground
+python3.12 -m venv venv && source venv/bin/activate
+pip install -e "..[viz]" plotly kaleido
+# drop your own alphadra_*.fits files in playground/datas/alphadra/
+python analyse_alpha_dra.py
+# → output/alpha_dra_*.png + alpha_dra_summary.csv
+```
+
+## Takeaways
+
+- **A 70-year-old published orbital period drops out of 240 amateur
+  spectra**, recovered to better than 1 % from the same kernel pipeline
+  that loads, normalises, and fits H-α on every file.
+- **The eccentric character of the orbit is visible** in the shape of the
+  phase-folded curve, without ever explicitly fitting a Kepler model.
+- **The principal axis of the embedding latent space *is* the orbital
+  phase**. Project the 240 vectors onto their first two PCs, colour by
+  phase: you get a smooth gradient. The DCT recipe, given nothing but
+  flux, ended up encoding the Doppler shift as a vector dimension — a
+  free property to exploit for clustering and similarity search.
+- This is also the **first concrete demonstration** that amateur
+  spectroscopy at moderate resolution is more than sufficient to do real
+  binary-star science when the data are reduced through a consistent,
+  reproducible pipeline. The kernel didn't need any α-Dra-specific
+  tuning — it's the same `snr_der → normalize → fit_gaussian_line` recipe
+  used on α Cyg, run on 240 files instead of 18.

spectro_kernel-0.1.4/src/spectro_kernel/algorithms/__init__.py

@@ -0,0 +1,17 @@
+"""The algorithm catalogue.
+
+Importing this package is a no-op: it does **not** trigger algorithm
+discovery on its own. Discovery is driven from
+:func:`spectro_kernel.registry.ensure_discovered`, which is called
+lazily by every registry getter (``list_algorithms``, ``get_algorithm``,
+``run_algorithm``, …). This keeps importing helpers from inside the
+``algorithms.*`` tree (for example
+``spectro_kernel.algorithms._common``) free of any circular-import
+hazard.
+
+Adding a new algorithm is still as simple as dropping a file under
+``algorithms/<category>/`` with a ``@register_algorithm`` decorator —
+the lazy walk picks it up the first time the registry is queried.
+"""
+
+from __future__ import annotations