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

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

@@ -6,6 +6,42 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.1.2
+Version: 0.1.3
 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.3/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.3/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.3/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

spectro_kernel-0.1.3/src/spectro_kernel/algorithms/io/read_sdss.py

@@ -0,0 +1,121 @@
+"""Algorithm: read an SDSS spectrum (loglam-based binary table)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import numpy as np
+from astropy.io import fits
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, Spectrum1D, WorkContext
+
+
+@register_algorithm("read_sdss_spectrum", category=AlgorithmCategory.IO, version="1.0.0")
+class ReadSdssSpectrum(BaseAlgorithm):
+    """Read an SDSS-format spectrum (``spec-*.fits``) into ``ctx.spectrum``.
+
+    SDSS spectra store the wavelength axis as ``loglam`` (log10 of the
+    wavelength in Å) and the flux as ``flux`` in a binary-table extension.
+    This is incompatible with the generic ``read_fits`` algorithm (which
+    looks for a column named ``wavelength``/``wave``/``lambda``), so we
+    handle it explicitly here.
+
+    The reader:
+
+    1. Opens the file (local path or http(s) URL).
+    2. Locates the spectrum extension — typically HDU 1 (``COADD``), with
+       ``flux``, ``loglam``, ``ivar`` columns.
+    3. Converts ``loglam`` → linear Å.
+    4. Converts inverse variance ``ivar`` → 1σ uncertainty.
+    5. Returns a ``Spectrum1D`` in the kernel's canonical form.
+
+    Flux units in SDSS are 10⁻¹⁷ erg/s/cm²/Å — stored as-is in
+    ``Spectrum1D.flux_unit`` for downstream sanity.
+    """
+
+    backend = "astropy"
+    references = [
+        "York et al. 2000, AJ, 120, 1579 — Sloan Digital Sky Survey overview.",
+        "Smee et al. 2013, AJ, 146, 32 — SDSS BOSS spectrograph and data format.",
+        "Bolton et al. 2012, AJ, 144, 144 — DR9 spectroscopic data release "
+        "documenting the spec-*.fits layout.",
+    ]
+    long_description = (
+        "Reading ``loglam``-based spectra is the one big gap of the generic "
+        "FITS reader — this algorithm closes it. Compatible with SDSS DR9 "
+        "through the current DR (the ``COADD`` HDU layout has been stable "
+        "since DR9)."
+    )
+    default_params = {"path": None}
+    required_params = ["path"]
+    param_descriptions = {
+        "path": "Local path or http(s) URL of an SDSS spec-*.fits file."
+    }
+    input_requirements: list[str] = []
+    output_produces = ["spectrum"]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        path = params["path"]
+        with fits.open(path) as hdulist:
+            hdu = _find_spectrum_hdu(hdulist)
+            if hdu is None:
+                return AlgorithmOutput.fail(
+                    f"No SDSS spectrum extension found in {os.path.basename(str(path))}; "
+                    "expected an extension with 'flux' + 'loglam' columns."
+                )
+            data = hdu.data
+            loglam = np.asarray(data["loglam"], dtype=np.float64).ravel()
+            flux = np.asarray(data["flux"], dtype=np.float64).ravel()
+            wavelength = np.power(10.0, loglam)
+            uncertainty: np.ndarray | None = None
+            if "ivar" in data.names:
+                ivar = np.asarray(data["ivar"], dtype=np.float64).ravel()
+                with np.errstate(divide="ignore", invalid="ignore"):
+                    uncertainty = np.where(ivar > 0.0, 1.0 / np.sqrt(ivar), np.nan)
+
+            mask: np.ndarray | None = None
+            if "and_mask" in data.names:
+                mask = np.asarray(data["and_mask"], dtype=np.int64).ravel() != 0
+
+        meta: dict[str, Any] = {"source": str(path), "format": "sdss"}
+        # Carry the standard SDSS keywords if present (helpful for downstream tools).
+        with fits.open(path) as hdulist:
+            primary = hdulist[0].header
+            for key in ("PLUG_RA", "PLUG_DEC", "PLATE", "MJD", "FIBERID", "OBJTYPE"):
+                if key in primary:
+                    meta[key.lower()] = primary[key]
+
+        ctx.spectrum = Spectrum1D(
+            wavelength=wavelength,
+            flux=flux,
+            uncertainty=uncertainty,
+            mask=mask,
+            wavelength_unit="Angstrom",
+            flux_unit="1e-17 erg/s/cm2/Angstrom",
+            meta=meta,
+        )
+        return AlgorithmOutput.ok(
+            metrics={
+                "npix": float(wavelength.size),
+                "wavelength_min": float(wavelength.min()),
+                "wavelength_max": float(wavelength.max()),
+            },
+            message=(
+                f"Loaded SDSS spectrum: {wavelength.size} pixels, "
+                f"{wavelength.min():.0f}-{wavelength.max():.0f} Å."
+            ),
+        )
+
+
+def _find_spectrum_hdu(hdulist: fits.HDUList) -> fits.BinTableHDU | None:
+    """Return the first BinTableHDU that has 'flux' + 'loglam' columns."""
+    for hdu in hdulist:
+        if not isinstance(hdu, fits.BinTableHDU) or hdu.data is None:
+            continue
+        names = {n.lower() for n in hdu.data.names}
+        if "flux" in names and "loglam" in names:
+            return hdu
+    return None

{spectro_kernel-0.1.2 → spectro_kernel-0.1.3}/src/spectro_kernel/registry.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import importlib
 import inspect
+import pkgutil
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
@@ -152,15 +153,35 @@ def register_algorithm(
 
 
 def ensure_discovered() -> None:
-    """Import the ``algorithms`` package once so every algorithm self-registers.
-
-    Called automatically by the discovery functions below; safe to call repeatedly.
+    """Import every algorithm submodule once so each ``@register_algorithm`` runs.
+
+    Called automatically by the registry getter functions below; safe to call
+    repeatedly. Discovery is **lazy** on purpose: importing
+    ``spectro_kernel.algorithms`` (the package) used to trigger eager
+    submodule discovery via the package's ``__init__``, which created a
+    circular-import hazard for any module that pulled even one helper out of
+    the ``algorithms`` tree before its own top-level definitions had run
+    (notably ``spectro_kernel.embeddings`` which uses
+    ``algorithms._common.fit_polynomial_continuum_asymmetric``).
+    Triggering discovery here, only when something actively asks the
+    registry for an algorithm, sidesteps that hazard entirely.
     """
     global _discovered
     if _discovered:
         return
-    importlib.import_module("spectro_kernel.algorithms")
+    # Mark *before* the walk so any algorithm that re-enters the registry
+    # during its own import (rare but possible) doesn't recurse infinitely.
     _discovered = True
+    pkg = importlib.import_module("spectro_kernel.algorithms")
+    for module_info in pkgutil.walk_packages(pkg.__path__, prefix=pkg.__name__ + "."):
+        try:
+            importlib.import_module(module_info.name)
+        except Exception:  # noqa: BLE001 - optional algorithms may need extras
+            # An algorithm whose dependencies aren't installed should not break
+            # discovery of the others. The algorithm will simply not appear in
+            # the registry; users who actually try to call it get a clear
+            # ImportError from inside its own module.
+            continue
 
 
 def has_algorithm(name: str) -> bool:

{spectro_kernel-0.1.2 → spectro_kernel-0.1.3}/src/spectro_kernel/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"