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

{spectro_kernel-0.1.0 → spectro_kernel-0.1.2}/.gitignore

@@ -221,3 +221,9 @@ __marimo__/
 # These are kept on disk for the maintainer but never committed: not on
 # GitHub, not in the PyPI sdist, not on the docs site.
 stuff/
+
+# Playground — personal FITS files, generated plots and the local venv.
+# The example script and README ARE tracked; only user data + outputs are not.
+playground/datas/
+playground/output/
+playground/venv/

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

@@ -6,6 +6,105 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.1.2] — 2026-06-05
+
+### Added — embedding category (8 algorithms total)
+
+The kernel grows a new `embedding` category. Eight algorithms ship together;
+all write to `ctx.embedding` (new typed slot) and to
+`ctx.extras['embedding_provenance']` (recipe + version + parameters — what a
+similarity layer needs to decide which vectors to re-index when an algorithm
+evolves). Catalogue size: 75 → 83.
+
+**Core (no extra dependencies — numpy / scipy only):**
+
+- `embed_spectrum` — three baseline recipes on the raw flux array:
+  - `naive`           : linear resample to `dim` + L2 norm.
+  - `dct`             : DCT-II coefficients truncated to `dim` + L2 norm.
+  - `multiscale_dct`  : DCT at four Gaussian scales (σ = 1, 2, 4, 8) + L2 norm.
+  Older strategy names `pca` and `autoencoder` still work but emit a
+  `DeprecationWarning`.
+- `embed_log_lambda` — resample to a uniform log-wavelength grid before
+  embedding. Two spectra of the same object at different radial velocities
+  produce shifted but similar shapes on this grid, so embeddings here are
+  more **Doppler-robust** than on the raw axis.
+- `embed_band_power` — split the wavelength range into N adjacent bands,
+  integrate the flux in each. Output is a very compact (8–32 dim) vector
+  that mimics multiband photometry; robust to dispersion differences
+  between instruments.
+- `embed_continuum_subtracted` — subtract the polynomial continuum first,
+  embed the line residual only. Decouples shape from absolute flux level;
+  two observations of the same star at different airmass yield very similar
+  embeddings under this recipe.
+- `embed_lick_indices` — the classical 17-element Lick/IDS feature vector
+  (Worthey 1994 + Trager 1998). Every dimension is a named, physically
+  interpretable index (Hβ → age, Mgb → [Mg/Fe], TiO → Teff, …). Compact
+  and explainable, at the cost of being visible-spectrum-only (4000–6500 Å).
+
+**Optional extras (no kernel install bloat):**
+
+- `embed_wavelets` — discrete wavelet transform (PyWavelets) + truncate to
+  the largest-magnitude coefficients. Better than DCT for spectra dominated
+  by sharp, localised features. Requires the extra
+  `pip install 'spectro-kernel[embedding-wavelets]'`.
+- `embed_remote` — call a remote inference endpoint over HTTP, get back the
+  embedding as JSON. Allows plugging in a heavy ML model hosted elsewhere
+  (your own MCP cloud, a HuggingFace Inference Endpoint, …) without
+  installing torch locally. Requires `[embedding-remote]` (httpx only).
+- `embed_pretrained` — load a local PyTorch model and run inference. For
+  users who actually want a learned encoder (Spender, AstroCLIP,
+  custom-trained on their dataset). Requires `[embedding-ml]` (torch); the
+  kernel install stays light by default — torch is **not** pulled by `[all]`.
+
+### Façade for batch use
+
+- New module `spectro_kernel.embeddings` with `embed(spectrum, …)` and
+  `embed_flux(flux, …)` — the same recipes as the algorithm, exposed as
+  pure functions. A downstream indexer can batch-embed thousands of spectra
+  without paying the per-call `WorkContext` / `ProcessingStep` overhead.
+
+### Pipeline preset
+
+- New `embed_quick.yaml` — normalise the continuum then embed (DCT, dim 256).
+  Drop it onto any spectrum with `spectro pipeline embed_quick` for an
+  immediate searchable vector.
+
+### Internals
+
+- `algorithms/_common.fit_polynomial_continuum_asymmetric` — sigma-clipped
+  polynomial continuum fit with asymmetric clip thresholds (favours
+  rejecting absorption over emission). Used by `embed_spectrum` when
+  `norm_method='continuum'` and available to any future algorithm that
+  needs the same recipe.
+- `numpy.trapz` was deprecated in numpy 2.0; the embedding algorithms now
+  import `numpy.trapezoid` with a fallback for older numpy.
+
+### Tests
+
+- 30+ new unit tests covering shape, L2 invariance, dim respected,
+  parameter validation, algorithm vs façade parity, recipe fidelity,
+  Doppler robustness (log-lambda), scale invariance (continuum-subtracted),
+  pipeline preset end-to-end, `WorkContext` summary + hash integration.
+  Total suite: 138 → 157 passing (+3 skipped on optional extras).
+
+## [0.1.1] — 2026-06-03
+
+### Added — full-resolution spectrum retrieval over MCP
+
+- New transverse MCP tool **`get_spectrum_data`** that returns the
+  current session spectrum as full-length wavelength + flux arrays
+  (via `Spectrum1D.to_dict()`). The existing `get_spectrum_preview`
+  still returns the 50-sample summary; use the new tool when a client
+  needs to plot or re-analyse the spectrum at full resolution.
+- Catalogue tool count online: 87 → 88.
+
+### Changed
+
+- `pyproject.toml` author renamed `Matthieu` → `matthieulel` so the
+  PyPI page matches the GitHub handle.
+
+## [0.1.0] — 2026-06-03 (initial PyPI release)
+
 ### Changed — keep deployment runbooks + internal design notes out of the public artefacts
 
 - Moved `SPECTRO_KERNEL_IMPLEMENTATION.md`, `SPECTRO_PLATFORM_PROPOSAL.md`,

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.1.0
+Version: 0.1.2
 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/
 Project-URL: Source, https://github.com/matthieulel/spectro-kernel
 Project-URL: Issues, https://github.com/matthieulel/spectro-kernel/issues
 Project-URL: Changelog, https://github.com/matthieulel/spectro-kernel/blob/main/CHANGELOG.md
-Author: Matthieu
+Author: matthieulel
 License: MIT
 License-File: LICENSE
 Keywords: astronomy,fits,mcp,pipeline,spectroscopy
@@ -37,10 +37,12 @@ Requires-Dist: easyspec>=1.0; extra == 'all'
 Requires-Dist: emcee>=3.1; extra == 'all'
 Requires-Dist: fastmcp>=2.0; extra == 'all'
 Requires-Dist: h5py>=3.10; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
 Requires-Dist: matplotlib>=3.8; extra == 'all'
 Requires-Dist: photutils>=2.0; extra == 'all'
 Requires-Dist: plotly>=5.20; extra == 'all'
 Requires-Dist: pyvo>=1.5; extra == 'all'
+Requires-Dist: pywavelets>=1.5; extra == 'all'
 Requires-Dist: redis>=5.0; extra == 'all'
 Requires-Dist: sentry-sdk>=2.0; extra == 'all'
 Requires-Dist: uvicorn[standard]>=0.30; extra == 'all'
@@ -55,6 +57,12 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: embedding-ml
+Requires-Dist: torch>=2.2; extra == 'embedding-ml'
+Provides-Extra: embedding-remote
+Requires-Dist: httpx>=0.27; extra == 'embedding-remote'
+Provides-Extra: embedding-wavelets
+Requires-Dist: pywavelets>=1.5; extra == 'embedding-wavelets'
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=2.0; extra == 'mcp'
 Requires-Dist: redis>=5.0; extra == 'mcp'

spectro_kernel-0.1.2/playground/README.md

@@ -0,0 +1,99 @@
+# spectro-kernel playground
+
+A separate sandbox for trying the library **as an end user would**: its own
+virtual environment, its own installed copy of `spectro-kernel`, isolated
+from the development venv at the repo root.
+
+## Setup (one-shot, ~3 min)
+
+From this directory:
+
+```bash
+# 1. fresh venv just for the playground
+python3.12 -m venv venv
+source venv/bin/activate
+
+# 2. install spectro-kernel in editable mode from the parent repo,
+#    with the [viz] extra for the Plotly plots.
+pip install -e "..[viz]"
+
+# 3. plotly is required to write the HTML files
+pip install plotly
+```
+
+Once PyPI publication is done you'll replace step 2 with simply
+`pip install "spectro-kernel[viz]"` — but for now the editable install
+lets you test the *exact* code in the repository.
+
+## Run
+
+Three flavours of the same end-to-end recipe:
+
+```bash
+source venv/bin/activate                 # if not already in
+
+# A. Library, full output (2 interactive HTML plots)
+python quickstart.py
+python quickstart.py <filename.fits>     # specific file
+
+# B. Library, minimal stdout, 1 PNG  (needs kaleido: `pip install kaleido`)
+python quickstart_min.py
+python quickstart_min.py <filename.fits>
+
+# C. Same recipe, but every call goes over JSON-RPC to the cloud MCP server.
+#    Needs fastmcp: `pip install fastmcp`. Uses a public CALSPEC Sun
+#    spectrum since the cloud server can't reach your local FITS files.
+python quickstart_mcp.py
+```
+
+Override the MCP URL with `SPECTRO_MCP_URL=...` (for testing a stdio server
+through an HTTP wrapper, a different DO deploy, etc.).
+
+You will see something like:
+
+```
+=== α Cyg quickstart — alphacyg_20231006185128_gbertrand.fits ===
+
+📥 loaded:  5925 pixels · 6496.8-6687.8 Angstrom
+📊 SNR (DER_SNR):  124.6
+🖼  raw plot:       output/alphacyg_20231006185128_gbertrand__01_raw.html
+✨ normalised:     continuum_median was 1875  → flux now ~1.0
+🔭 detected:       1 line(s) matched against the Balmer catalogue
+     · H-alpha   6562.81 Å  (absorption)
+🖼  normalised plot:output/alphacyg_20231006185128_gbertrand__02_normalised.html
+```
+
+Open the two HTML files in your browser to inspect the spectra interactively.
+
+## What's in here
+
+| Path | Role | In Git? |
+|------|------|---------|
+| `quickstart.py` | The example script — read it as a guided tour | ✅ |
+| `README.md` | This file | ✅ |
+| `datas/alphacygni/*.fits` | Your personal spectra | ❌ gitignored |
+| `output/*.html` | Generated Plotly HTML | ❌ gitignored |
+| `venv/` | Local virtualenv | ❌ gitignored |
+
+## What the script does
+
+1. **Loads** one FITS spectrum into a `Spectrum1D` and parks it in a `WorkContext`.
+2. **`snr_der`** — derivative-based SNR estimate (DER_SNR, Stoehr+ 2008).
+3. **`plot_spectrum_plotly`** — first plot, raw spectrum.
+4. **`normalize_polynomial`** — polynomial continuum fit (order 3), flux divided
+   so the continuum lands near 1.0.
+5. **`detect_lines`** with the `balmer` catalogue — finds H-alpha (and any other
+   Balmer line that happens to be in the wavelength range).
+6. **`plot_spectrum_plotly`** again, this time on the normalised spectrum, with
+   red vertical markers at each detected line.
+
+Every step is a normal `run_algorithm(...)` call against the same shared
+`WorkContext` — exactly the same recipe a real pipeline would use.
+
+## Going further
+
+- Edit `quickstart.py` to try other algorithms — e.g. `fit_gaussian_line` to
+  fit H-alpha properly, or `barycentric_correction` to apply the heliocentric
+  velocity correction.
+- Loop over every file in `datas/alphacygni/` to build a time series.
+- Use `stack_spectra` to coadd them (drop them into `ctx.spectra` first).

{spectro_kernel-0.1.0 → spectro_kernel-0.1.2}/pyproject.toml

@@ -9,7 +9,7 @@ description = "A shared catalogue of astronomical spectroscopy algorithms, compo
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.11"
-authors = [{ name = "Matthieu" }]
+authors = [{ name = "matthieulel" }]
 keywords = ["astronomy", "spectroscopy", "fits", "pipeline", "mcp"]
 classifiers = [
   "Development Status :: 3 - Alpha",
@@ -52,6 +52,12 @@ mcp = [
   "uvicorn[standard]>=0.30",
 ]
 monitoring = ["sentry-sdk>=2.0"]
+# Embedding extras — kept thin on purpose so the kernel install stays light.
+# Algorithms register themselves regardless; they fail with a clear error
+# pointing at the right extra when their dependency is missing.
+embedding-wavelets = ["pywavelets>=1.5"]
+embedding-remote = ["httpx>=0.27"]      # client for an external inference endpoint
+embedding-ml = ["torch>=2.2"]           # local PyTorch model inference
 dev = [
   "pytest>=8.0",
   "pytest-cov>=5.0",
@@ -63,7 +69,10 @@ docs = [
   "mkdocs-gen-files>=0.5",
 ]
 all = [
-  "spectro-kernel[catalogs,viz,storage,reduction,mcp,monitoring]",
+  "spectro-kernel[catalogs,viz,storage,reduction,mcp,monitoring,embedding-wavelets,embedding-remote]",
+  # NOTE: embedding-ml (torch) is intentionally NOT pulled by [all] — torch is
+  # a multi-gigabyte install. Users who want local PyTorch embeddings opt in
+  # explicitly with [embedding-ml].
 ]
 
 [project.scripts]

{spectro_kernel-0.1.0 → spectro_kernel-0.1.2}/src/spectro_kernel/algorithms/_common.py

@@ -45,6 +45,42 @@ def fit_polynomial_continuum(
     return np.polynomial.Polynomial.fit(x[mask], y[mask], deg=order)(x)
 
 
+def fit_polynomial_continuum_asymmetric(
+    flux: np.ndarray,
+    *,
+    order: int = 6,
+    iterations: int = 5,
+    sigma_low: float = 1.5,
+    sigma_high: float = 3.0,
+) -> np.ndarray:
+    """Asymmetric sigma-clipped polynomial continuum fit.
+
+    Companion to :func:`fit_polynomial_continuum` (symmetric clip): rejecting
+    absorption lines more aggressively (``sigma_low``) than emission lines
+    (``sigma_high``) is what you want when the continuum sits *above* the
+    lines, as in most stellar spectra. The wavelength axis is normalised to
+    ``[-1, 1]`` internally so callers can pass a raw flux array without
+    worrying about polynomial conditioning.
+    """
+    n = int(flux.size)
+    x = np.linspace(-1.0, 1.0, n)
+    mask = np.ones(n, dtype=bool)
+    coeffs = np.zeros(order + 1)
+    for _ in range(max(1, iterations)):
+        if mask.sum() < order + 1:
+            break
+        coeffs = np.polyfit(x[mask], flux[mask], order)
+        continuum = np.polyval(coeffs, x)
+        residuals = flux - continuum
+        sigma = float(np.std(residuals[mask]))
+        if sigma == 0.0:
+            break
+        mask = (residuals > -sigma_low * sigma) & (residuals < sigma_high * sigma)
+    if mask.sum() >= order + 1:
+        coeffs = np.polyfit(x[mask], flux[mask], order)
+    return np.polyval(coeffs, x)
+
+
 def r_squared(observed: np.ndarray, modelled: np.ndarray) -> float:
     """Return the coefficient of determination of *modelled* against *observed*."""
     observed = np.asarray(observed, dtype=np.float64)

spectro_kernel-0.1.2/src/spectro_kernel/algorithms/embedding/embed_band_power.py

@@ -0,0 +1,140 @@
+"""Algorithm: band-power embedding — integrated flux in N wavelength bands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+# numpy renamed trapz -> trapezoid in 2.0; support both.
+try:
+    from numpy import trapezoid as _trapezoid
+except ImportError:  # pragma: no cover - numpy < 2.0
+    from numpy import trapz as _trapezoid
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+
+
+@register_algorithm(
+    "embed_band_power",
+    category=AlgorithmCategory.EMBEDDING,
+    version="1.0.0",
+)
+class EmbedBandPower(BaseAlgorithm):
+    """Embed a spectrum as the integrated flux in N adjacent wavelength bands.
+
+    The wavelength range is split into ``n_bands`` non-overlapping bands;
+    each band's value is the trapezoidal integral of the flux within it.
+    Optionally takes a logarithm to compress the dynamic range (~ astronomical
+    magnitudes), then L2-normalises the vector. The output captures the gross
+    shape of the spectral energy distribution while being **very compact**
+    (typically 8–32 dimensions) and **robust to resolution differences**
+    between instruments — band sums average over many pixels.
+
+    Spacing can be linear or logarithmic in wavelength; logarithmic is the
+    natural choice for stellar spectra (matches the spacing of photometric
+    filter systems like SDSS *ugriz* or 2MASS *JHK*).
+    """
+
+    backend = "numpy"
+    references = [
+        "Connolly et al. 1995, AJ, 110, 1071 — photometric SED classification.",
+        "Bolzonella et al. 2000, A&A, 363, 476 — band-power feature vectors "
+        "for spectro-photometric classification.",
+    ]
+    long_description = (
+        "Equivalent to converting a spectrum into a 'virtual photometric "
+        "catalogue' with N synthetic broad bands. Very cheap and well-suited "
+        "to indexing very heterogeneous datasets (different dispersions, "
+        "resolutions, telescopes)."
+    )
+    default_params: dict[str, Any] = {
+        "n_bands": 16,
+        "spacing": "log",      # linear | log
+        "log_flux": True,
+        "epsilon": 1.0e-12,    # added before log to avoid -inf on zero bands
+    }
+    param_descriptions = {
+        "n_bands": "Number of bands; also the output dim. Typically 8–32.",
+        "spacing": "Band edges in wavelength: 'linear' or 'log'.",
+        "log_flux": "Take log10(integrated_flux + epsilon) before L2 norm.",
+        "epsilon": "Small floor added before log_flux to keep zero bands finite.",
+    }
+    input_requirements = ["spectrum"]
+    output_produces = [
+        "embedding",
+        "extras.embedding_provenance",
+        "metrics.embedding_dim",
+        "metrics.embedding_norm",
+    ]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        if spec is None or spec.flux is None or spec.flux.size == 0:
+            return AlgorithmOutput.fail(
+                "embed_band_power requires a non-empty spectrum on ctx.spectrum."
+            )
+
+        n_bands = int(params["n_bands"])
+        if n_bands <= 0:
+            raise InvalidParameterError("n_bands must be a positive integer.")
+        spacing = str(params["spacing"]).lower()
+        if spacing not in ("linear", "log"):
+            raise InvalidParameterError("spacing must be 'linear' or 'log'.")
+        if spacing == "log" and float(spec.wavelength_min) <= 0.0:
+            return AlgorithmOutput.fail(
+                "spacing='log' requires strictly positive wavelengths; "
+                "use spacing='linear' or call extract_region first."
+            )
+
+        wave = np.asarray(spec.wavelength, dtype=np.float64)
+        flux = np.asarray(spec.flux, dtype=np.float64)
+
+        if spacing == "linear":
+            edges = np.linspace(spec.wavelength_min, spec.wavelength_max, n_bands + 1)
+        else:
+            edges = np.exp(
+                np.linspace(
+                    np.log(spec.wavelength_min),
+                    np.log(spec.wavelength_max),
+                    n_bands + 1,
+                )
+            )
+
+        band_power = np.empty(n_bands, dtype=np.float64)
+        for i in range(n_bands):
+            mask = (wave >= edges[i]) & (wave <= edges[i + 1])
+            if mask.sum() < 2:
+                band_power[i] = 0.0
+            else:
+                band_power[i] = float(_trapezoid(flux[mask], wave[mask]))
+
+        if bool(params["log_flux"]):
+            band_power = np.log10(np.abs(band_power) + float(params["epsilon"]))
+
+        norm = float(np.linalg.norm(band_power))
+        if norm > 0.0:
+            band_power = band_power / norm
+
+        ctx.embedding = band_power
+        ctx.extras["embedding_provenance"] = {
+            "algorithm": "embed_band_power",
+            "n_bands": n_bands,
+            "spacing": spacing,
+            "log_flux": bool(params["log_flux"]),
+            "band_edges": edges.tolist(),
+            "version": self.version,
+        }
+        ctx.metrics["embedding_dim"] = float(n_bands)
+        ctx.metrics["embedding_norm"] = float(np.linalg.norm(band_power))
+        return AlgorithmOutput.ok(
+            metrics={
+                "embedding_dim": float(n_bands),
+                "embedding_norm": float(np.linalg.norm(band_power)),
+            },
+            artifacts={"provenance": ctx.extras["embedding_provenance"]},
+            message=f"Band-power embedded ({n_bands} {spacing}-spaced bands).",
+        )

spectro_kernel-0.1.2/src/spectro_kernel/algorithms/embedding/embed_continuum_subtracted.py

@@ -0,0 +1,132 @@
+"""Algorithm: embed only the line residual after subtracting the continuum."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ...base import AlgorithmOutput, BaseAlgorithm
+from ...embeddings import VALID_NORM_METHODS, VALID_STRATEGIES, embed_flux
+from ...errors import InvalidParameterError
+from ...registry import register_algorithm
+from ...types import AlgorithmCategory, WorkContext
+from .._common import fit_polynomial_continuum
+
+
+@register_algorithm(
+    "embed_continuum_subtracted",
+    category=AlgorithmCategory.EMBEDDING,
+    version="1.0.0",
+)
+class EmbedContinuumSubtracted(BaseAlgorithm):
+    """Subtract the polynomial continuum, then embed the line residual.
+
+    Decouples the *shape* of the spectrum (its absorption / emission lines)
+    from its *absolute flux level* (continuum). Two observations of the same
+    object at different airmass — and therefore different continua — should
+    yield very similar embeddings under this recipe, even when the raw
+    spectra look obviously different in flux.
+
+    Equivalent to chaining the existing ``subtract_continuum`` algorithm and
+    ``embed_spectrum`` in a pipeline; kept as a single registered algorithm
+    so callers don't have to author a pipeline and so a single provenance
+    record describes the whole flow.
+    """
+
+    backend = "scipy"
+    references = [
+        "Sousa et al. 2007, A&A, 469, 783 — continuum-normalised spectra for "
+        "stellar parameter retrieval.",
+        "Worthey et al. 1994, ApJS, 94, 687 — line-strength indices on "
+        "continuum-flattened spectra.",
+    ]
+    long_description = (
+        "Uses the symmetric sigma-clipped polynomial continuum helper from "
+        "``algorithms._common``; the residual (flux - continuum) is then "
+        "passed to one of the standard embedding recipes. Set "
+        "``norm_method='none'`` to skip a second normalisation step — the "
+        "residual already has zero mean."
+    )
+    default_params: dict[str, Any] = {
+        "dim": 256,
+        "strategy": "dct",
+        "continuum_order": 3,
+        "sigma_clip": 3.0,
+        "norm_method": "none",
+    }
+    param_descriptions = {
+        "dim": "Output vector length (positive integer).",
+        "strategy": (
+            f"Recipe applied to the residual: one of {VALID_STRATEGIES}."
+        ),
+        "continuum_order": "Polynomial degree for the continuum fit (2-5 typical).",
+        "sigma_clip": "Sigma threshold for the continuum-fit clip (default 3.0).",
+        "norm_method": (
+            f"Pre-embedding flux normalisation: one of {VALID_NORM_METHODS}. "
+            "Defaults to 'none' because the residual is already zero-centred."
+        ),
+    }
+    input_requirements = ["spectrum"]
+    output_produces = [
+        "embedding",
+        "extras.embedding_provenance",
+        "metrics.embedding_dim",
+        "metrics.embedding_norm",
+        "metrics.continuum_rms",
+    ]
+
+    def run(self, ctx: WorkContext, params: dict[str, Any]) -> AlgorithmOutput:
+        spec = ctx.spectrum
+        if spec is None or spec.flux is None or spec.flux.size == 0:
+            return AlgorithmOutput.fail(
+                "embed_continuum_subtracted requires a non-empty spectrum on ctx.spectrum."
+            )
+
+        wave = np.asarray(spec.wavelength, dtype=np.float64)
+        flux = np.asarray(spec.flux, dtype=np.float64)
+
+        continuum = fit_polynomial_continuum(
+            wave,
+            flux,
+            order=int(params["continuum_order"]),
+            sigma_clip=float(params["sigma_clip"]),
+        )
+        residual = flux - continuum
+        rms = float(np.std(residual))
+
+        try:
+            vec = embed_flux(
+                residual,
+                dim=int(params["dim"]),
+                strategy=str(params["strategy"]),
+                norm_method=str(params["norm_method"]),
+            )
+        except ValueError as exc:
+            raise InvalidParameterError(str(exc)) from exc
+
+        ctx.embedding = vec
+        ctx.extras["embedding_provenance"] = {
+            "algorithm": "embed_continuum_subtracted",
+            "strategy": str(params["strategy"]),
+            "dim": int(vec.size),
+            "continuum_order": int(params["continuum_order"]),
+            "sigma_clip": float(params["sigma_clip"]),
+            "norm_method": str(params["norm_method"]),
+            "version": self.version,
+        }
+        ctx.metrics["embedding_dim"] = float(vec.size)
+        ctx.metrics["embedding_norm"] = float(np.linalg.norm(vec))
+        ctx.metrics["continuum_rms"] = rms
+        return AlgorithmOutput.ok(
+            metrics={
+                "embedding_dim": float(vec.size),
+                "embedding_norm": float(np.linalg.norm(vec)),
+                "continuum_rms": rms,
+            },
+            artifacts={"provenance": ctx.extras["embedding_provenance"]},
+            message=(
+                f"Continuum-subtracted embedded ({params['strategy']}, "
+                f"dim={vec.size}, residual RMS={rms:.4g})."
+            ),
+        )