spectro-kernel 0.6.2__tar.gz → 0.7.0__tar.gz

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/.gitignore

@@ -166,6 +166,7 @@ venv.bak/
 
 # documentation - generated by tools/docs/generate.py
 docs/algorithms/
+docs/recipes/catalogue/
 docs/ai/
 docs/llms.txt
 

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/CHANGELOG.md

@@ -6,6 +6,246 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-09-26
+
+The release that turns presets into **recipes** : a measurement written once,
+with its conventions fixed and everything instrument-dependent declared as a
+variable, so that observers with different spectrographs produce comparable
+numbers. It also lands the bricks those recipes need for pro-am campaigns
+(time-series line-profile analysis, the flux-calibration chain, stellar
+activity and rotation indicators, resolving power, spline continuum) and a
+FITS reader that copes with the amateur "zoo". Numerical changes are carried
+by MAJOR bumps of the bricks concerned and listed below.
+
+### Added — recipes, variables and profiles (presets v2)
+
+- A preset may declare a `variables` block (`type` among `str`, `int`,
+  `float`, `bool`, `path`, `list`; `default`, `required`, `description`,
+  `choices`) and reference them as `"${name}"` in step parameters. The
+  values come from a **profile** (`spectro pipeline <recipe> --profile
+  file.yaml`), from `--set name=value` (converted to the declared type),
+  from `PipelineBuilder().from_preset(name, variables={...})` /
+  `from_config(config, variables)`, or from the `variables` argument of
+  the MCP `run_preset` tool. Defaults fill the gaps ; a missing required
+  variable, an undeclared token or a value of the wrong type is refused
+  before anything runs, with the variable's description in the message.
+  A preset without `variables` is unchanged.
+- `requires: ">=0.7, <1.0"` : the kernel range a recipe was validated for
+  (plain comparison operators) ; a recipe outside the range refuses to build.
+- Standard metadata vocabulary : `kind` (`analysis`, `reduction`,
+  `campaign`, `template`), `status` (`draft`, `reviewed`, `reference`),
+  `references` (mandatory for a campaign recipe), `conventions`.
+- **Discovery** : besides the bundled catalogue, the kernel lists recipes
+  from every directory in `SPECTRO_PRESET_PATH` and from installed
+  packages registering the `spectro_kernel.presets` entry point (a
+  `Path` to a directory of YAML files). `list_presets()` reports each
+  recipe's `source` ; a bundled name wins over an external one.
+- **Validation** : `spectro preset validate <file-or-name>...` (also
+  `--profile` / `--set` to type-check values) reports every problem at
+  once : name not snake_case, missing or malformed version, missing
+  description, unknown `kind` / `status`, campaign recipe without
+  references, unsatisfied `requires`, unknown algorithm, unknown parameter,
+  required parameter neither set nor bound, undeclared token, unused
+  variable, `depends_on` matching no step. `spectro preset show <name>`
+  prints a recipe's variables and steps ; `spectro presets` shows the
+  source and the number of variables. Python : `validate_preset`,
+  `validate_preset_file`, `preset_sources`, `find_preset`.
+- **Provenance** : every named pipeline built from a file or a config
+  closes its run with a `pipeline:<name>` `ProcessingStep` carrying the
+  recipe version, the bound variables, the kernel version and the source,
+  so a result states which recipe produced it. Ad-hoc pipelines assembled
+  in Python without a name are unchanged.
+- The bundled `full_reduction_easyspec` template (2.0.0) replaces its
+  `__REPLACE__` placeholders by ten declared variables (`bias_dir`,
+  `dark_dir`, `flat_dir`, `science_path`, `exposure_seconds`, `airmass`,
+  `gain`, `readnoise`, `target_name`, `combine_method`) ; the six analysis
+  presets gain `kind` and `status` metadata. The preset file format is
+  published as `preset.schema.json`.
+- The curated collection lives in a separate repository,
+  [spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+  (`pip install spectro-kernel-recipes`), starting with `be_halpha_ew`,
+  `binary_rv_ccf`, `solar_long_slit` and `stellar_long_slit` (all `draft`).
+
+### Added — time-series line-profile analysis (category `timeseries`, `stacking`)
+
+- **`temporal_variance_spectrum` v1.0.0** (scipy) — Fullerton, Gies & Bolton
+  1996, ApJS 103, 475, §3 : N ≥ 3 continuum-normalised epochs in
+  `ctx.spectra`, resampled on the finest common grid over the overlap ;
+  per-epoch noise σ_ic from `uncertainty` or DER_SNR on a continuum window
+  (`continuum_lo` / `continuum_hi`) ; weights w_i = (σ_0/σ_ic)² with
+  σ_0 = [(1/N) Σ σ_ic⁻²]^(−1/2) ; (TVS)_j = (N−1)⁻¹ Σ_i w_i (S_ij − S̄_j)² ;
+  reported as (TVS)^{1/2} with the χ²_(N−1) significance threshold at
+  `confidence` (0.99). Writes `extras.tvs` and the `tvs_*` metrics, the
+  bounds of the longest significant run as `tvs_variable_lo_aa` /
+  `tvs_variable_hi_aa`. Caveat documented : the pixel-dependent
+  photon-noise term α_ij of the paper is not applied (uniform noise across
+  the profile). Tests : variability confined to |v| < 120 km/s → 71 % of
+  pixels flagged inside, 2.2 % beyond 200 km/s ; no variability → 1.2 %
+  above the 99 % threshold ; threshold exact to 1e-12.
+- **`phase_dispersion_minimization` v1.0.0** (numpy) — Stellingwerf 1978,
+  ApJ 224, 953 : Θ = s²/σ² over M = N_b·N_c overlapping phase samples
+  (`n_bins` 10, `n_covers` 3), uniform frequency grid (`n_periods` 2000),
+  light-curve input exactly as `lomb_scargle`. `ctx.periodograms[key]`
+  carries Θ with `meta.lower_is_better` ; metrics `pdm_best_period_days`,
+  `pdm_theta_min`. No false-alarm probability on purpose
+  (Schwarzenberg-Czerny 1997, ApJ 489, 941). Tests : eclipse and sawtooth
+  signals at 3.7 d over 60 d recovered to 0.11 % ; pure noise → Θ ≈ 1.00.
+- **`box_least_squares` v1.0.0** (astropy) — Kovács, Zucker & Mazeh 2002,
+  A&A 391, 369, wrapping `astropy.timeseries.BoxLeastSquares` ;
+  `duration_hours` list, `objective` likelihood / snr ; periodogram plus
+  `extras.bls_model` and the `bls_*` metrics. Without uncertainties the
+  noise is 1.4826·MAD (Rousseeuw & Croux 1993) instead of astropy's
+  implicit σ = 1 (which gave a 41-σ transit an SNR of 0.09). Tests :
+  P = 2.5 d, depth 1 %, 3 h box on a 30 d series → period to 0.012 %,
+  depth to 1.8 %, SNR 41.
+- **`stack_spectra` 2.0.0 → 2.1.0** (additive) : `method: "weighted"`, the
+  Bevington & Robinson inverse-variance mean with the stack uncertainty
+  (Σ w)^(−1/2) ; weights from the `weights` parameter, else from every
+  spectrum's `uncertainty`, else from DER_SNR² (Tody 1993, IRAF `scombine`).
+  mean / median / sum are bit-identical to v2.0.0. Test : σ = 1 and 2 →
+  weights 4:1, output σ = 1/√1.25.
+
+### Added — flux-calibration chain (categories `correction`, `catalog`, `nebular`)
+
+- **`atmospheric_extinction_correct` v1.0.0** (numpy) — F_0 = F·10^{0.4 k(λ) X}
+  (Hayes & Latham 1975, ApJ 197, 593 ; Hardie 1962). Built-in `curve`
+  `"kpno"`, the IRAF `onedstds$kpnoextinct.dat` mean extinction table
+  (3200–10400 Å, Tody 1986 ; all 82 nodes checked against the IRAF source,
+  the last four being CTIO values), or a user table in `ctx.extras`. Airmass from
+  `airmass`, else from the header / site with Kasten & Young 1989, Appl.
+  Opt. 28, 4735, eq. 3. Uncertainty scaled with the flux. Metrics
+  `airmass`, `k_mag_median`, `n_outside_curve`.
+- **`deredden_interstellar` v1.0.0** (dust_extinction, optional extra
+  `reduction`) — F_0 = F / 10^{−0.4 A(λ)} with CCM89 (Cardelli, Clayton &
+  Mathis 1989, ApJ 345, 245 ; default), F99 (Fitzpatrick 1999, PASP 111,
+  63) or G23 (Gordon et al. 2023, ApJ 950, 86) ; `ebv`, `rv` (3.1) ; fails
+  outside a law's validity range. Test : CCM89, R_V = 3.1, E(B−V) = 0.1 at
+  5500 Å → factor 10^{0.4·0.31} = 1.330, checked against the package.
+- **`standard_star_reference` v1.0.0** (astropy ; network, lazy) — loads a
+  CALSPEC standard (Bohlin, Gordon & Tremblay 2014, PASP 126, 711 ; Bohlin,
+  Hubeny & Rauch 2020, AJ 160, 21) by name or `filename` from the STScI
+  reference-atlas archive through the SSRF-guarded fetch with timeout and
+  size cap, or a Pickles 1998 (PASP 110, 863) template ; vacuum → air with
+  Morton 2000 (`to_air`) ; writes `extras.catalog_spectrum` (rename with
+  `output_key`, e.g. to `reference_spectrum` for `response_from_standard`).
+  Pickles templates are normalised to unity at 5556 Å by construction
+  (Pickles 1998, §3 and §5) and passed through unchanged ; the brick reports
+  `flux_at_5556_aa` so the caller can see it.
+- **`balmer_decrement_extinction` v1.0.0** (scipy) — c(Hβ), E(B−V) and A_V
+  from the observed Hα/Hβ ratio against Case B 2.86 (Osterbrock & Ferland
+  2006, Table 4.4, §7.2) with the CCM89 f(λ) ; negative extinction clamped
+  to 0 with a note ; metrics `balmer_ratio_observed`, `c_hbeta`,
+  `ebv_balmer`, `a_v_balmer`, `flux_halpha`, `flux_hbeta`.
+
+### Changed — uncertainties are now propagated (MAJOR bumps ; flux byte-identical)
+
+Until now every one of these bricks copied the input `uncertainty` array
+unchanged, which is wrong after any of them. Each now documents its rule ;
+a spectrum without uncertainty is processed exactly as before.
+
+- `smooth_gaussian` 1.0.1 → 2.0.0 and `smooth_savgol` 1.0.1 → 2.0.0 :
+  σ_out,i = sqrt(Σ_k w_k² σ²) with the very kernel applied (Gaussian
+  truncated at 4σ ; Savitzky-Golay coefficients incl. the edge polynomials).
+  White noise, sigma = 2 px → σ_out = 0.376 σ in the interior and 0.641 σ
+  at the first and last samples (the 'nearest' edge weights add before
+  squaring) ; window 11 / order 3 → 0.4555 σ. Both checked against the full
+  linear operator to 1e-9 and by Monte-Carlo. Correlated noise is not
+  tracked (documented).
+- `normalize_polynomial` 1.1.1 → 2.0.0, `normalize_to_region` 1.0.1 →
+  2.0.0, `normalize_max` 1.0.2 → 2.0.0, `normalize_percentile` 1.0.2 →
+  2.0.0, `normalize_edges` 1.0.2 → 2.0.0 : σ_out = σ_in / |continuum|,
+  continuum treated as noise-free.
+- `resample_linear` 1.0.1 → 2.0.0 : σ_out = sqrt(interp(σ²)) (linear
+  interpolation of the variance ; v1 interpolated σ itself).
+- `combine_spectra_arithmetic` 1.0.1 → 2.0.0 : add/sub in quadrature ;
+  mul/div with the relative errors in quadrature when the reference
+  carries an uncertainty (Bevington & Robinson §3.2), else σ·|r| or σ/|r|.
+
+### Added — stellar activity, rotation, resolution, continuum (new category `activity`)
+
+- **`activity_index_caii_hk` v1.0.0** (numpy, `activity`) — the Mount
+  Wilson S index, S = α (H + K)/(R + V) with the HKP-2 triangular 1.09 Å
+  H and K bands and the 20 Å R and V bands (Vaughan, Preston & Wilson 1978,
+  PASP 90, 267 ; Duncan et al. 1991, ApJS 76, 383), `alpha` 2.3 (échelle
+  convention, Lovis et al. 2011) with an optional linear calibration to the
+  Mount Wilson scale ; log R'_HK when `b_v` is given (Noyes et al. 1984,
+  ApJ 279, 763 ; Middelkoop 1982, A&A 107, 31). Fails outside 3890–4011 Å.
+- **`activity_index_halpha` v1.0.0** (numpy, `activity`) — Gomes da Silva
+  et al. 2011, A&A 534, A30 (after Boisse et al. 2009, A&A 495, 959) : 1.6 Å
+  core at 6562.808 Å over the 6550.87 ± 5.375 Å and 6580.31 ± 4.375 Å
+  reference bands ; `halpha_index` and its error.
+- **`ccf_bisector` v1.0.0** (numpy, `activity`) — bisector of the CCF
+  written by `cross_correlate_rv` (or of one line of the spectrum) after
+  Toner & Gray 1988, ApJ 334, 1008, and the bisector inverse slope BIS =
+  v_top(10–40 %) − v_bottom(55–90 %) of Queloz et al. 2001, A&A 379, 279 ;
+  `bis_kms`, `bisector_span_kms`, `extras.ccf_bisector`. Symmetric profile
+  → BIS = 0 within 0.01 km/s.
+- **`vsini_fourier` v1.0.0** (scipy, `kinematics`) — v sin i from the first
+  zero of the Fourier transform of a line profile (Carroll 1933, MNRAS 93,
+  478 ; Gray 2005, ch. 18) with q₁(ε) from Dravins, Lindegren & Nordlund
+  1990, A&A 228, 203 (`epsilon` 0.6 → q₁ = 0.660) ; the first zero is
+  accepted only when the side lobe stands above the Fourier noise floor
+  (`metrics.fourier_noise_floor`, `fourier_sidelobe_ratio`), and unresolved,
+  emission or noise-dominated lines fail explicitly. Tests : 30, 80 and
+  150 km/s recovered within 5 % at 0.5 % noise. Reference to the modern
+  recipe : Díaz, González, Levato & Grosso 2011, A&A 531, A143.
+- **`measure_resolving_power` v1.0.0** (scipy, `quality`) — R = λ/FWHM from
+  Gaussian fits of the `n_lines` strongest isolated lamp / sky lines
+  (isolation by `min_separation_aa`), median and scatter of R, instrumental
+  FWHM in Å and km/s (Gray 2005, ch. 12 ; Tody 1986, IRAF `splot`). Test :
+  12 lines of FWHM = λ/5000 → R = 5000 ± 2 %.
+- **`normalize_spline` v1.0.0** (scipy, `continuum`) — the IRAF
+  `continuum` recipe (Tody 1986 ; Tody 1993) : iteratively clipped cubic
+  spline (`n_knots`, `low_reject` 2.0, `high_reject` 3.0, `niterate` 10,
+  `grow` 0), `extras.continuum_spline`, σ/continuum propagated ;
+  cross-references `normalize_polynomial`.
+
+### Changed — FITS reading and writing (`read_fits` 2.0.0 → 3.0.0, `io/fits.py`)
+
+The reader now takes explicit, documented decisions on the FITS "zoo"
+(audit items C6 / C7) ; 37 new tests in `test_io_fits_zoo.py`.
+
+- `CD1_1` wins over `CDELT1` when both exist (Greisen & Calabretta 2002 ;
+  v2 preferred `CDELT1`), `PC1_1` scales `CDELT1` ; `CUNIT1` (or IRAF
+  `WAT1` units) in nm / µm / m converted to Å with the original label in
+  `meta["wavelength_unit_original"]` ; WAVE-LOG (Paper III) and IRAF
+  `DC-FLAG` handling unchanged.
+- No dispersion keywords → 0-based pixel axis, `wavelength_unit="pixel"`,
+  `meta["wcs"]="none"` (v2 labelled the pixel index "Angstrom").
+- A genuine 2-D image is refused unless the new `row` parameter selects a
+  row (v2 silently returned row 0) ; length-1 axes are squeezed ; IRAF
+  multispec / échelle markers redirect to `read_echelle_fits` ; 3-D cubes
+  are refused.
+- Extension selection : a data-bearing PRIMARY wins over tables (v2
+  preferred any table) ; otherwise the first table with recognisable
+  wavelength / flux columns (incl. SDSS `loglam`) ; the new `hdu`
+  parameter (index or EXTNAME) overrides ; when nothing is readable the
+  error lists the HDUs found.
+- `ERROR` / `ERR` / `ERRS` / `SIGMA` / `UNCERT(AINTY)` (1σ) and `IVAR`
+  (1/√ivar) image extensions and error / ivar table columns fill
+  `uncertainty` ; `MASK` extensions and `mask` / `and_mask` columns fill
+  `mask` ; `BUNIT` becomes the flux unit ; descending axes are kept and
+  flagged `meta["wavelength_descending"]`.
+- `write_fits` : the linear layout now appends `ERROR` and `MASK`
+  extensions when the spectrum carries them, read back by `read_fits`
+  (round-trip tested) ; a spectrum without either is still a single HDU.
+
+
+### Documentation
+
+- A new **Recipes** section (the recipe / profile idea, the format
+  reference, how to share a recipe) and a generated recipe catalogue with
+  one page per recipe plus `/ai/presets.json` ; the CLI, MCP, pipelines and
+  reduction-walkthrough pages updated accordingly.
+
+- The long-slit tutorial is now worked on a **solar** spectrum (Fraunhofer
+  wavelength calibration, no lamp) with a **stellar** arc-lamp variant ;
+  the aurora example is gone. Its code samples were also corrected : the
+  2-D reduction runs from Python (`spectro pipeline` loads 1-D spectra) and
+  the lamp hand-off uses the real `lamp_identifications` keys.
+- The BeSS-dashboard cookbook page is removed ; the aurora line-monitor
+  notebook is parked in `docs/.drafts/` (not published) for a later return.
+
 ## [0.6.2] — 2026-09-19
 
 A documentation and web release : the docs move to a generated,

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.6.2
+Version: 0.7.0
 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://docs.spectrokernel.io/
@@ -210,6 +210,16 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
 | `SENTRY_DSN` | unset | Error reporting. |
 
+## Recipes and profiles
+
+A recipe (preset) is a measurement written once with its conventions fixed;
+what depends on your instrument is a variable, bound by a profile at run
+time: `spectro pipeline be_halpha_ew --input obs.fits --profile my_setup.yaml`.
+Generic recipes ship with the kernel; campaign recipes live in the curated
+[spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+collection (`pip install spectro-kernel-recipes`). See the
+[Recipes](https://docs.spectrokernel.io/recipes/) documentation.
+
 ## Architecture
 
 ```

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/README.md

@@ -121,6 +121,16 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
 | `SENTRY_DSN` | unset | Error reporting. |
 
+## Recipes and profiles
+
+A recipe (preset) is a measurement written once with its conventions fixed;
+what depends on your instrument is a variable, bound by a profile at run
+time: `spectro pipeline be_halpha_ew --input obs.fits --profile my_setup.yaml`.
+Generic recipes ship with the kernel; campaign recipes live in the curated
+[spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+collection (`pip install spectro-kernel-recipes`). See the
+[Recipes](https://docs.spectrokernel.io/recipes/) documentation.
+
 ## Architecture
 
 ```

spectro_kernel-0.7.0/docs/.drafts/README.md

@@ -0,0 +1,7 @@
+# Drafts (not published)
+
+Pages parked here are excluded from the site: both Zensical and MkDocs skip
+dot-directories. Move a page back under `docs/` (and add it to the `nav` in
+`mkdocs.yml`) to publish it again.
+
+- `notebooks/aurora-line-monitor.md` - parked on 2026-09-19, to be reinstated later.

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/docs/concepts/pipelines.md

@@ -90,7 +90,12 @@ spectro pipeline balmer_quick --input obs.fits    # run one
 ```
 
 Presets are why an analysis can be cited and reproduced: *"this measurement used the
-`balmer_quick` v1.0.0 preset"* is a precise, checkable statement.
+`balmer_quick` v1.0.0 preset"* is a precise, checkable statement. Since v0.7.0 a
+preset can declare **variables** (the instrument- or observer-dependent values)
+that a **profile** supplies at run time, and every run closes with a
+`pipeline:<name>` record in the history naming the recipe, its version and the
+bound values. The [Recipes](../recipes/index.md) section explains the idea and
+the [format](../recipes/format.md) page is the reference.
 
 ## Reproducibility {#reproducibility}
 

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/docs/notebooks/be-star-variability.md

@@ -63,8 +63,8 @@ natural answer; today the cleanest path is the Python snippet above.)
 
 ## Going further
 
-- Replace the synthetic spectra with real BeSS extractions - see the
-  [BeSS cookbook page](../cookbook/bess-dashboard.md).
+- Replace the synthetic spectra with real BeSS extractions: `read_fits` reads
+  them directly (see [As a Python library](../usage/library.md)).
 - Add `compare_normalisations` (Tier 2+) before stacking when continuum
   variations between nights are suspect.
 - Couple it with `lomb_scargle` on a per-epoch line-strength metric to look for

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/docs/notebooks/claude-mcp-end-to-end.md

@@ -136,7 +136,7 @@ beyond `spectro-mcp --http`.
   workflows (e.g. "always run `compare_normalisations` before measuring a
   line").
 - Wrap the agent in a periodic task (cron + a Claude API call) for nightly
-  monitoring - Be-star variability alerts, aurora amplitude history,
+  monitoring - Be-star variability alerts, solar line monitoring,
   exoplanet RV drift.
 - Pair with the [web playground](../cookbook/web-playground.md) for human-in-the-loop
   debugging when the agent picks the wrong tool.

{spectro_kernel-0.6.2 → spectro_kernel-0.7.0}/docs/notebooks/full-reduction-walkthrough.md

@@ -109,30 +109,40 @@ run_algorithm(
 # → ctx.spectrum.flux is now in erg/s/cm²/Å.
 ```
 
-## The same as a preset
+## The same as a recipe
+
+The whole chain (steps 1-3, the file-driven portion) is the bundled recipe
+`full_reduction_easyspec`. Everything that depends on your night is a
+variable of the recipe; you supply the values with a profile:
+
+```yaml
+# night_2026-06-09.yaml
+bias_dir: /data/biases
+dark_dir: /data/darks
+flat_dir: /data/flats
+science_path: /data/science/alf_cyg_001.fits
+exposure_seconds: 300
+airmass: 1.18
+target_name: alf Cyg
+```
+
+```bash
+spectro preset show full_reduction_easyspec          # the variables and their meaning
+spectro pipeline full_reduction_easyspec --profile night_2026-06-09.yaml
+```
 
-The whole chain (steps 1-3 - the parameter-free, file-driven portion) is
-templated in the bundled preset
-[`full_reduction_easyspec`](https://github.com/matthieulel/spectro-kernel/blob/main/src/spectro_kernel/presets/catalog/reduction/full_reduction_easyspec.yaml).
-It is a *template*: the `__REPLACE__` placeholders are the runtime paths you fill
-in before building the pipeline. A typical usage:
+Or from Python:
 
 ```python
-from spectro_kernel import PipelineBuilder, WorkContext
-from spectro_kernel.presets import load_preset
-
-config = load_preset("full_reduction_easyspec")
-for step in config["steps"]:
-    p = step["params"]
-    for key, value in p.items():
-        if isinstance(value, str) and value.startswith("__REPLACE_WITH_BIAS_DIR__"):
-            p[key] = "/data/biases"
-        elif isinstance(value, str) and value.startswith("__REPLACE_WITH_DARK_DIR__"):
-            p[key] = "/data/darks"
-        # … etc.
-
-pipeline = PipelineBuilder().from_config(config).build()
+import yaml
+
+from spectro_kernel import WorkContext
+from spectro_kernel.pipeline import PipelineBuilder
+
+profile = yaml.safe_load(open("night_2026-06-09.yaml"))
+pipeline = PipelineBuilder().from_preset("full_reduction_easyspec", profile).build()
 result = pipeline.execute(WorkContext())
+print(result.history[-1])   # pipeline:full_reduction_easyspec v2.0.0, the bound variables
 ```
 
 Steps 4-6 (wavelength + extinction + flux) stay separate calls because their

spectro_kernel-0.7.0/docs/recipes/format.md

@@ -0,0 +1,163 @@
+---
+description: Reference for the recipe (preset) file, its variables, profiles, validation and provenance.
+---
+
+# Recipe format
+
+A recipe is one YAML file. The schema is published at
+[`/ai/schemas/preset.schema.json`](../ai/schemas/preset.schema.json) and
+`spectro preset validate` checks a file against the running kernel: format,
+metadata vocabulary, algorithm names, parameter names, variables, and the
+kernel version range.
+
+## The file
+
+```yaml
+name: be_halpha_ew            # lowercase snake_case; the identifier users cite
+version: 1.0.0                # semantic version of the recipe itself
+description: >-
+  What is measured and how, in one paragraph.
+requires: ">=0.7, <1.0"       # spectro-kernel range the recipe was validated for
+metadata:
+  kind: campaign              # analysis | reduction | campaign | template
+  status: reviewed            # draft | reviewed | reference
+  references:                 # mandatory for a campaign recipe
+    - "Vollmann & Eversberg 2006, AN 327, 862"
+  conventions: "continuum band 6500-6520 Å, 40 Å window around H-alpha"
+  author: "BeSS working group"
+variables:                    # what depends on the instrument or the observer
+  tilt_deg: {type: float, required: true, description: "slit tilt (deg)"}
+  half_width: {type: int, default: 6}
+steps:                        # the pipeline, in order
+  - name: Straighten the slit
+    algorithm: correct_tilt_affine
+    params: {tilt_deg: "${tilt_deg}"}
+```
+
+`name`, `version`, `description` and `steps` are required. A recipe with no
+`variables` block is a plain preset and runs as is; every preset written
+before v0.7.0 is still valid.
+
+## Variables
+
+Each variable has a `type`, an optional `default`, a `description`, and
+optionally a list of `choices`. A variable without a default is required.
+The shorthand `half_width: 6` declares an optional integer with that default.
+
+| Type | Accepts | Example values |
+|---|---|---|
+| `int` | integers, or strings such as `"12"` from the command line | `6` |
+| `float` | numbers | `0.4` |
+| `bool` | booleans, or `true/false`, `yes/no`, `on/off`, `1/0` | `true` |
+| `str` | text | `"alf Cyg"` |
+| `path` | a file or directory path, kept as text | `/data/bias` |
+| `list` | a YAML list, a JSON list such as `"[1, 2]"`, or `"a, b"` | `[5852.49, 6266.50]` |
+
+Values coming from `--set name=value` are strings and are converted to the
+declared type; a value outside `choices` or of the wrong type is refused
+with the variable's name and description in the message.
+
+## Substitution rules
+
+The rules are deliberately small:
+
+- a parameter whose value is exactly `${name}` receives the variable's typed
+  value (a number stays a number, a list stays a list);
+- a string that contains `${name}` among other text is interpolated as text
+  (`label: "H-${line}"`), useful for labels and file names;
+- lists and mappings are walked recursively;
+- every `${name}` must be declared in `variables`, and every declared variable
+  must be used, otherwise validation fails.
+
+Write the token in quotes, `"${name}"`: YAML would otherwise read the braces
+of `{tilt_deg: ${tilt_deg}}` as a nested mapping. The quotes change nothing
+for the kernel, which still passes the typed value.
+
+## Profiles
+
+A profile is any YAML mapping of variable name to value. It carries no
+science, only what is true of one instrument and one observer:
+
+```yaml
+# lhires_lyon.yaml
+tilt_deg: 1.1
+half_width: 4
+```
+
+Ways to bind values, in increasing priority:
+
+| From | How |
+|---|---|
+| the recipe | `default` of each variable |
+| a profile file | `spectro pipeline <recipe> --profile lhires_lyon.yaml` |
+| the command line | `--set tilt_deg=1.1` (repeatable) |
+| Python | `PipelineBuilder().from_preset("be_halpha_ew", {"tilt_deg": 1.1})` |
+| MCP | `run_preset(session_id, "be_halpha_ew", variables={"tilt_deg": 1.1})` |
+
+Keep your profiles next to your data, one per instrument setup, and reuse
+them across every recipe: the same `alpy600_toulouse.yaml` serves the Be
+star recipe tonight and the nova recipe next month.
+
+## `requires`
+
+The kernel version range the recipe was validated for, with the plain
+comparison operators (`>=`, `>`, `<=`, `<`, `==`, `!=`, comma-separated). A
+recipe whose range excludes the running kernel refuses to build. When a
+brick used by a recipe changes its own major version (its numbers changed),
+the recipe author re-validates and bumps the recipe.
+
+## Metadata vocabulary
+
+| Key | Values | Meaning |
+|---|---|---|
+| `kind` | `analysis`, `reduction`, `campaign`, `template` | what the recipe is for; a *campaign* recipe fixes a measurement convention for a community |
+| `status` | `draft`, `reviewed`, `reference` | how far the review went (see [Share a recipe](share.md)) |
+| `references` | list of strings | the papers the conventions rest on; mandatory for `campaign` |
+| `conventions` | text | the choices that are not fixed by the literature, stated plainly |
+| `author`, `notes`, `expects`, `category` | text | free information shown on the recipe page |
+
+## Validation
+
+```bash
+spectro preset validate be_halpha_ew.yaml                 # the file alone
+spectro preset validate be_halpha_ew.yaml --profile p.yaml # plus your values
+spectro preset show be_halpha_ew                           # variables and steps
+```
+
+Validation is what the CI of a recipe collection runs on every contribution.
+It reports, all at once: a name that is not snake_case, a missing or malformed
+version, a missing description, an unknown `kind` or `status`, a campaign
+recipe without references, a `requires` range the kernel does not satisfy,
+an unknown algorithm, an unknown parameter name, a required parameter that is
+neither set nor bound to a variable, an undeclared `${token}`, an unused
+variable, and a `depends_on` that matches no step.
+
+## Provenance
+
+When a recipe runs, every brick records itself in the context history as
+before, and the run closes with one more record:
+
+```text
+algorithm    pipeline:be_halpha_ew
+version      1.0.0
+params       {variables: {...}, n_steps: 4, kernel_version: 0.7.0, source: package:spectro-kernel-recipes}
+```
+
+It is written by `Pipeline.execute` for every named pipeline built from a
+file or a config, and carried into every export that serialises the history.
+Ad-hoc pipelines assembled in Python without a name leave the history exactly
+as their steps wrote it.
+
+## Discovery
+
+`spectro presets` lists every recipe the kernel can see, in this search order:
+
+1. the recipes bundled with the kernel;
+2. the directories listed in the `SPECTRO_PRESET_PATH` environment variable
+   (`:`-separated on macOS and Linux);
+3. installed packages that register an entry point in the
+   `spectro_kernel.presets` group (see [Share a recipe](share.md)).
+
+A bundled name always wins over an external one with the same name. A recipe
+can also be run from a path (`spectro pipeline ./my_recipe.yaml`). Nothing is
+ever fetched from the network.