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

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

@@ -164,6 +164,11 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
+# documentation - generated by tools/docs/generate.py
+docs/algorithms/
+docs/ai/
+docs/llms.txt
+
 # mkdocs documentation
 /site
 
@@ -222,6 +227,9 @@ __marimo__/
 # GitHub, not in the PyPI sdist, not on the docs site.
 stuff/
 
+# Node — the website's dependencies (never committed, never in the sdist).
+node_modules/
+
 # 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/

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

@@ -6,6 +6,400 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-09-19
+
+A documentation and web release : the docs move to a generated,
+agent-readable site at https://docs.spectrokernel.io/, the landing page is
+rebuilt around the open MCP server, and the server gains CORS so the web
+playground can use it. No algorithm changes.
+
+### MCP server
+
+- CORS for browser clients in HTTP mode : `SPECTRO_MCP_CORS_ORIGINS`
+  (default : the spectrokernel.io sites ; `*` or `none`), with the
+  `Mcp-Session-Id` header exposed, so the web playground on the landing
+  page can talk to the public server. Pre-flights are answered before the
+  API-key check.
+
+### Documentation — new build pipeline and hosting (no package change)
+
+- The site is now built with **Zensical** (the Material for MkDocs team's
+  successor engine, reading the unchanged `mkdocs.yml`) and published at
+  **https://docs.spectrokernel.io/** by Netlify, which builds it from the
+  repository (base directory `tools/docs`, see `tools/docs/netlify.toml`) ;
+  pull requests get a deploy preview and GitHub Actions keeps a strict build
+  check. `mkdocs build` keeps working as a fallback.
+- The algorithm catalogue is generated *before* the build by
+  `tools/docs/generate_catalogue.py` (Zensical runs no MkDocs plugin such as
+  `gen-files`) : one page per algorithm under `/algorithms/<category>/<name>/`
+  (summary, backend, version, context reads/writes, parameter table, Python /
+  CLI / MCP call examples, references, related algorithms), a category index,
+  and a navigation tree consumed by `literate-nav`.
+- Machine-readable layer for agents and tooling : `/ai/algorithms.json`
+  (validated at build time against `/ai/schemas/algorithms.schema.json`,
+  schema version 1, stamped with the package version), a curated `/llms.txt`
+  derived from the navigation, and the Markdown source of every page served
+  next to its HTML (`<page>/index.md`). Netlify headers set the content types
+  and CORS on `/ai/*`.
+- `tools/docs/build.py` reproduces the CI build locally (generators + strict
+  build + post-processing) ; `tools/docs/generate.py && zensical serve` for
+  live preview. Generated files (`docs/algorithms/`, `docs/ai/`,
+  `docs/llms.txt`) are git-ignored. `.readthedocs.yaml` and
+  `docs/gen_catalogue.py` are removed ; the `docs` extra now installs
+  `zensical`, `mkdocstrings[python]`, `mkdocs-material`,
+  `mkdocs-literate-nav`, `jsonschema`.
+
+## [0.6.1] — 2026-09-19
+
+A correctness and hardening release driven by a full audit of the
+library (`stuff/spectro_kernel_audit_19_09_26.md`, local) : one
+critical hole in the public MCP server, ten numerical bugs in the
+catalogue, and a long tail of robustness, reference and test fixes.
+No algorithm, parameter, context key or metric key is renamed or
+removed. Bricks whose numerical output changed carry a MAJOR bump of
+their own `version` attribute and the measured impact is listed below,
+so downstream pipelines can decide when to re-run. Catalogue unchanged
+at 115 algorithms ; 399 → 620+ tests.
+
+### Security — MCP server (`spectro-mcp --http`)
+
+- **Critical fix : every algorithm tool now goes through the path /
+  URL guards.** Until v0.6.0 only `load_spectrum` was guarded ; the
+  auto-generated tools ran `run_algorithm` bare, so in HTTP mode
+  `read_ascii_spectrum` / `read_fits` / `read_votable_spectrum` /
+  `read_echelle_fits` / `read_sdss_spectrum` could read any server
+  file, the `export_*` bricks could write anywhere, the EasySpec
+  wrappers could stage any directory, and `read_fits` /
+  `embed_remote` could reach loopback and metadata addresses.
+  `make_tool` now validates every parameter named `path`, `*_path`,
+  `*_paths`, `*_dir`, `model_path`, `target_path`, `endpoint`,
+  `atlas_dir` : local paths are refused under
+  `SPECTRO_MCP_DENY_LOCAL_PATHS` (set by `--http`), URLs go through the
+  SSRF guard, and URLs handed to a `read_*` brick are downloaded by the
+  MCP layer (no redirects, 256 MiB cap, wall-clock budget, concurrency
+  cap, pixel-count check) before the brick sees a temp file. `run_preset`
+  only accepts bundled preset names in HTTP mode. Regression tests drive
+  the real tool registry with the deny flag set.
+- `embed_remote` v1.0.1 : the server-side `SPECTRO_EMBED_API_KEY` is
+  no longer attached to an arbitrary caller-supplied endpoint ; in HTTP
+  mode it is sent only to hosts listed in `SPECTRO_EMBED_ENDPOINT_ALLOW`.
+- **HTTP mode now requires an explicit posture** : the server exits
+  (code 2) unless `SPECTRO_MCP_API_KEY` is set (closed) or
+  `SPECTRO_MCP_ALLOW_ANONYMOUS=1` is set on purpose (open). The public
+  demo server is open : `.do/app.yaml` declares
+  `SPECTRO_MCP_ALLOW_ANONYMOUS=1`, `SPECTRO_MCP_RATE_PER_MINUTE=60` and
+  `SPECTRO_MCP_TRUSTED_PROXY=1` (the closed variant is documented next to
+  it). README and `docs/usage/mcp.md` gain the full environment-variable
+  table. **Add `SPECTRO_MCP_ALLOW_ANONYMOUS=1` in the DigitalOcean console
+  before deploying this version**, otherwise the container refuses to
+  start.
+- Key carriers : besides `X-API-Key`, the middleware accepts
+  `Authorization: Bearer <key>` and, when `SPECTRO_MCP_ALLOW_KEY_IN_URL=1`,
+  `?api_key=…` in the URL, which is what claude.ai / Claude Desktop
+  custom connectors need (they cannot send headers). The parameter is
+  removed from the request scope after validation so uvicorn's access log
+  never records it.
+- Rate limiting : the API-key middleware is now outermost (401 before
+  any bucket is allocated), buckets are keyed on the validated key (or
+  the client IP when auth is off), idle buckets are evicted and the
+  table is capped ; `SPECTRO_MCP_TRUSTED_PROXY=1` makes uvicorn honour
+  `X-Forwarded-For` behind a load balancer. Key comparison is
+  constant-time (`hmac.compare_digest`).
+- Memory : live sessions are capped (`SPECTRO_MCP_MAX_SESSIONS`, default
+  200, LRU eviction, expired sessions purged on every `create`) ;
+  downloaded FITS files are refused above `SPECTRO_MCP_MAX_PIXELS`
+  (default 32 M elements, i.e. 256 MB as float64) before any conversion ;
+  `get_spectrum_data` returns at most `max_points` samples (default
+  20 000, stride-downsampled, with new fields `downsampled`,
+  `npix_total`, `npix_returned`, `stride` ; `max_points=0` returns
+  everything).
+- Downloads : per-download wall-clock budget
+  (`SPECTRO_MCP_DOWNLOAD_BUDGET_S`, 120 s, enforced inside the read loop
+  so a drip-feeding server cannot pin a worker thread) and a concurrency
+  cap (`SPECTRO_MCP_MAX_CONCURRENT_DOWNLOADS`, 4).
+- Information disclosure : `FastMCP(mask_error_details=True)` in HTTP
+  mode ; `get_algorithm_source` withholds the absolute install path
+  (`path: null`, repo-relative path and GitHub URL kept).
+- Every tool response is now strict JSON : `NaN` / `±inf` metrics are
+  serialised as `null`, numpy scalars as Python numbers (both channels).
+- `spectro_kernel.url_safety` (library guard) : refuses every
+  non-global address (adds CGNAT 100.64/10 and friends), judges NAT64
+  (`64:ff9b::/96`) and IPv4-mapped addresses on the embedded IPv4 (a
+  public host resolved through a DNS64 resolver was wrongly refused —
+  this was the one failing test), and `open_safe_url` pins the
+  connection to the validated address (one DNS lookup, closes the
+  rebinding window). The public-URL test no longer touches the network.
+- Dockerfile : the dependency layer is built from `pyproject.toml`
+  before `COPY src`, so source-only changes no longer reinstall the
+  scientific stack. Same specifiers, no lockfile.
+
+### Core
+
+- Registry discovery is thread-safe : `ensure_discovered()` runs under a
+  lock and flags completion only after the import walk. A thread pool
+  hitting the registry cold used to see `AlgorithmNotFoundError` on 5 of
+  6 threads. `clear_registry()` followed by any registry call now
+  restores the full catalogue.
+- Provenance hashing is memoised on array identity : a 4096² frame
+  hashes in 4 µs after the first 390 ms, so a six-step reduction on ten
+  raw frames no longer spends ~20 s re-hashing untouched inputs.
+  Digests are byte-identical to v0.6.0 for the same content. In-place
+  mutation of `Spectrum1D` / `ImageFrame` arrays after hashing is
+  unsupported (documented ; no brick does it).
+- Provenance correctness : `Spectrum1D.content_hash` now covers `mask`
+  and `WorkContext.hash_state` covers non-empty `extras`, `periodograms`,
+  `light_curves` and `exports`, so `mask_range`, `extract_sky_lateral_bands`,
+  `response_from_standard`, `lomb_scargle`, `synth_telluric`, `export_*`
+  no longer record `output_hash == input_hash`. Digests change only for
+  contexts that carry those slots. The MCP `load_spectrum*` tools append
+  a `load_spectrum` step when they replace the spectrum of a session
+  that already has history, so the input-hash chain stays valid.
+- `PipelineBuilder.from_config` : `params: null` is accepted ; a string
+  `depends_on` or a non-mapping `params` raise `PipelineError` instead of
+  a `TypeError` / silent character split. The CLI `pipeline` report is
+  built from the audit trail, so after an early stop in DAG mode it no
+  longer blames a step that never ran.
+- `Spectrum1D.wavelength_min/max` return `nan` on empty arrays ;
+  `preview()` never raises ; the MCP loaders return `{"error": …}` for
+  unreadable or empty inputs.
+- Packaging : the sdist no longer ships `website/` (153
+  `node_modules` files had leaked in), `playground/` or the Git-LFS
+  pointer stubs of `tests/reference/data` ; `node_modules/` is
+  git-ignored. CI gains a `test-extras` job installing `[all,dev]`, so
+  the EasySpec, plotly, photutils, h5py, astroquery and pywavelets tests
+  actually run on GitHub (they were always skipped there).
+
+### Fixed — numerical (MAJOR bump of the brick)
+
+- **`oiii_electron_temperature` 1.0.0 → 2.0.0.** The 7.90 prefactor of
+  Osterbrock & Ferland 2006 eq. 5.4 applies to
+  `[F(4959)+F(5007)]/F(4363)` ; the brick applied it to the 5007-only
+  ratio, biasing Te high by 9–16 % across the validity range. λ4959 is
+  now fitted too (new optional `lambda_4959`, default 4958.911 Å) with a
+  fallback to `F(5007)·(1+1/2.98)` (Storey & Zeippen 2000) when it
+  cannot be fitted or its measured 5007/4959 falls outside [2.0, 4.5].
+  Measured : spectrum with 5007/4363 = 100 → doublet ratio 133.6 →
+  **Te 12 961 K → 11 635 K** ; 5007/4363 = 50 → 17 830 → 15 413 K ;
+  200 → 10 181 → 9 344 K. `metrics.ratio` is now the doublet ratio ;
+  additive `oiii_ratio`, `oiii_ratio_doublet`, `ratio_5007_4363`,
+  `flux_4959`, `ratio_5007_4959`, `oiii_doublet_from_fit`,
+  `extras.oiii_doublet_source`. The acceptance test carries the
+  Osterbrock values.
+- **`doppler_tomogram` 1.0.0 → 2.0.0.** Back-projection used
+  `v = γ − Vx sin 2πφ + Vy cos 2πφ` ; Marsh & Horne 1988 eq. 1 is
+  `v = γ − Vx cos 2πφ + Vy sin 2πφ`. A spot with RV curve γ + K sin 2πφ
+  (the donor, MH position (0, +K)) landed at (−K, 0) : v1 maps are the
+  v2 maps rotated `(Vx, Vy) → (Vy, −Vx)`. Test generator switched to the
+  MH convention with an explicit (0, +K) assertion.
+
+- **`measure_arc_geometry` 1.0.0 → 2.0.0.** The returned `slant_deg`
+  had the opposite sign of what `correct_slant_affine` expects, so the
+  documented measure → correct chain doubled the slant instead of
+  removing it (synthetic +0.05 px/row arc : residual +0.10 px/row after
+  correction, now 0.0001). The sign is negated in the measuring brick
+  only ; `correct_slant_affine` is untouched, so hand-tuned preset angles
+  keep their meaning. Round-trip test added (the smile half of the chain
+  was already exact).
+- **`extract_spectrum_easyspec` 1.0.0 → 2.0.0.** The uint16
+  `BZERO`/`BSCALE` leak fixed in v0.2.1 for the `_easyspec_apply`
+  wrappers was still present in the extraction wrapper's own staging :
+  a uint16 science frame came back +32768. Structural and scaling
+  keywords are now filtered with the same `_filter_structural` helper.
+- **`extract_spectrum_sum` 1.0.0 → 2.0.0.** Its pixel axis was 1-based
+  (`arange(n) + 1`) while every other extractor, the lamp identifiers
+  and `wavelength_calibrate_polynomial` are 0-based : a sum-extracted
+  lamp calibrated through `match_lamp_lines` was off by one pixel
+  (+0.9 Å at 0.9 Å/px) with a clean RMS. Now 0-based ; the convention is
+  stated in both bricks.
+- **`extract_spectrum_boxcar` 1.0.0 → 2.0.0.** The sky estimate was
+  the mean of the two flanking windows with an empty window counted as
+  zero, and the windows are bounded by the *median* trace, so a tilted
+  trace halved the sky on many columns (audit scenario : 163 of 400
+  columns at sky = 50 instead of 100 ; now 0). Only non-empty windows
+  are averaged ; `metrics.boxcar_columns_without_sky` counts the columns
+  with neither. `shift_y_pixels` must now exceed `trace_half_width`
+  (it silently produced a zero sky otherwise) and negative values are
+  refused ; the two contradictory docstrings agree. Untilted traces are
+  bit-identical to v1.
+- **`stack_spectra` 1.0.0 → 2.0.0.** `np.interp` extrapolated each
+  spectrum's edge value across the whole reference grid : two spectra
+  covering 4000–5000 Å (flux 1) and 4500–5500 Å (flux 3) averaged to 2.0
+  at 4000 Å. Samples outside a spectrum's coverage are now NaN and
+  ignored by the combiners (also for `sum`) ; `metrics.n_nan_samples`
+  reports how many reference samples had no contributor. The brick also
+  gains a `backend` and a reference (Tody 1993, IRAF `scombine`).
+- **`dark_combine` 1.0.0 → 2.0.0, `flat_combine` 1.0.0 → 2.0.0.** The
+  sigma-clipped mean floored the MAD scale at machine epsilon, so any
+  stack with MAD = 0 (integer-ADU darks with ~1 ADU read noise) rejected
+  every value that differed from the median and degenerated to it
+  (`[10,10,10,11,12]` → 10.0). When MAD is zero the scale now falls back
+  to the mean absolute deviation about the median (Gaussian-scaled),
+  which still rejects a cosmic ray in that regime (`[10,10,10,11,1000]`
+  → 10.25, whereas a `nanstd` fallback would have kept it). Result :
+  10.6. Stacks with MAD > 0 are unchanged.
+- **`wavelength_calibration_solar` 1.0.0 → 2.0.0.** When several peaks
+  matched the same Fraunhofer line, the tie-break compared the catalogue
+  wavelength with itself and always kept the first peak ; it now keeps
+  the closest (a spurious dip 6 Å blueward of Hα no longer steals the
+  identification). New artifact `matched_pixels`.
+- **`read_fits` 1.0.0 → 2.0.0 (`io/fits.py`).** A `CTYPE1` ending in
+  `-LOG` (`WAVE-LOG`, `AWAV-LOG`) was decoded as IRAF log10, giving
+  `inf` everywhere ; it now follows WCS Paper III (Greisen et al. 2006)
+  λ = CRVAL1·exp((p − CRPIX1)·CDELT1/CRVAL1), verified against
+  `astropy.wcs` to 1e-9. `10**` applies only to `DC-FLAG = 1`. A `-LOG`
+  axis with `CRVAL1 = 0` raises `IOReadError`.
+
+### Changed — analysis-side bricks (additive, no numerical change for valid input)
+
+- `cross_correlate_rv` 2.0.0 → 2.1.0 : `n_grid=None` derives the
+  log-λ grid from the finest native sampling of the two spectra (capped
+  at 2^18). The default stays 4096, which is badly under-sampled for
+  high-resolution input : on a 30 000-pixel synthetic (σ_line 0.15 Å,
+  S/N 100) an injected +10 km/s comes back as +0.9 ± 0.15 km/s at the
+  default 41 km/s step and +9.97 ± 0.02 km/s with `n_grid=None`. σ_v
+  (Tonry & Davis) is documented as a lower bound at coarse grids. New
+  `metrics.n_grid_used`, `metrics.velocity_step_kms`,
+  `extras.template_source` ; the `ctx.spectra[0]` template fallback is
+  deprecated (`DeprecationWarning` + message) because it contradicts the
+  "second spectrum lives in `ctx.extras`" rule.
+- `equivalent_width` 1.0.0 → 1.1.0 : σ(EW) per Vollmann & Eversberg
+  2006 (AN 327, 862) eq. 7 as `metrics.equivalent_width_error_angstrom`
+  when the spectrum carries uncertainties ; new optional `label` with
+  per-label keys next to the flat ones ; references added.
+- `fit_keplerian_orbit` 1.0.0 → 1.1.0 : an explicit `0.0` initial guess
+  is honoured (`or` → `is None`) ; additive `reduced_chi_squared` when
+  RV uncertainties are present ; ω bounds and the unweighted
+  `chi_squared` documented as implemented.
+- `disentangle_sb2` 1.0.0 → 1.1.0 : cites Bagnuolo & Gies 1991 (ApJ
+  376, 266) as the implemented scheme, documents the additive continuum
+  degeneracy, adds `metrics.disentangle_residual_rms` ; first numerical
+  test.
+- `classify_template_chi2` 1.0.0 → 1.1.0 : `atlas_dir` (path) as an
+  alternative to the Python `atlas` object, so the brick is CLI/MCP
+  drivable ; `required_params` is now empty (one of the two is validated
+  at run time) ; per-template normalisation cached on the atlas
+  (identical numbers) ; `grid_lo/grid_hi/grid_step` documented as
+  reserved.
+- `sii_electron_density` 1.0.0 → 1.1.0, `bpt_line_ratios` 1.0.0 →
+  1.1.0 : prefixed keys (`sii_ratio`, `sii_regime`, `bpt_method`, …)
+  next to the generic `ratio` / `regime` / `method`, which the three
+  nebular bricks used to overwrite in a pipeline.
+- `lomb_scargle` 1.1.0 → 1.1.1 : the false-alarm probability is
+  evaluated on the frequency range actually searched (unchanged with
+  default bounds ; with `maximum_frequency=1.0` on the test series
+  1.85e-210 → 2.95e-211).
+- `redshift_lines` 1.0.0 → 1.0.1 : `z_error` documented as the
+  population std of the per-line z ; descending axes and non-finite
+  samples handled (v1 answered "0 lines matched") ; needs ≥ 6 finite
+  samples.
+
+### Changed — reduction-side bricks (additive / robustness)
+
+- `resample_flux_conserving` 1.0.0 → 1.0.1 : failed for the kernel's
+  own default flux unit (`ADU`) and for `counts` / `transmission`
+  because `astropy.units.Unit(..., parse_strict="silent")` returns an
+  `UnrecognizedUnit` instead of raising ; units are now mapped
+  (`adu`, `count`, else dimensionless). First tests for the brick,
+  including flux conservation on a top-hat to 1e-6.
+- `remove_telluric_division` 1.0.0 → 1.1.0 : when the default
+  `telluric_spectrum` key is absent it falls back to
+  `telluric_template_scaled` then `telluric_template`, so the documented
+  `synth_telluric → fit_telluric_scaling → remove_telluric_division`
+  chain works with defaults (in-band residual 0.40 → 0.03 on the test
+  case). Records `meta["telluric_template_key"]`.
+- EasySpec wrappers (all PATCH) : sessions are serialised behind one
+  lock, user paths are resolved to absolute before the working
+  directory switch, `stage_frames` tolerates duplicate basenames, and
+  the four wrappers that did their own `os.chdir` now use the shared
+  context manager. Cheap parameter validation in
+  `flux_calibrate_easyspec` / `extinction_correct_easyspec` /
+  `extract_spectrum_boxcar` runs before the EasySpec import, so
+  refusals are reachable without it.
+- `subtract_sky_2d` 1.0.0 → 1.0.1 : one 2-D `polyfit` instead of a
+  per-column loop (200×2048 : 0.21 s → 0.007 s, max |Δ| 6e-14, tested
+  against the verbatim v1 loop for orders 0–3).
+- `outlier_rejection_mad_adaptive` 1.0.0 → 1.0.1 : rows are processed
+  in chunks sized from a 64 MB budget (a 2048², k = 5 frame needed
+  ~0.8 GB transient) ; bit-identical output, tested.
+- `export_hdf5` 1.0.1 (file-descriptor leak), `resample_linear` 1.0.1
+  (own header dict), `response_from_standard` / `flat_normalize` /
+  `flat_combine` docstrings aligned with the code (no masking, global
+  median normalisation imprints the lamp continuum, `spline_knots` is a
+  smoothing factor, exposure-time normalisation is the caller's job).
+
+### Fixed — robustness (PATCH bumps)
+
+- NaN no longer yields `success=True` with garbage : `snr_edge`,
+  `snr_linear_fit` (SNR = inf) and `normalize_edges` (all-NaN output)
+  mask non-finite samples and fail when too few remain ; the
+  `embed_*` family fails cleanly (or drops non-finite samples where the
+  recipe is sampling-independent : `embed_band_power`,
+  `embed_lick_indices`, `embed_log_lambda`) instead of returning a zero
+  vector ; `smooth_gaussian` / `smooth_savgol` bridge NaN before
+  filtering and restore it afterwards (one NaN used to spread over 34
+  pixels, Savitzky-Golay used to raise). `embed_flux` raises
+  `ValueError` on non-finite input.
+- Descending wavelength axes (negative `CDELT1`, reversed ASCII tables)
+  are sorted locally in `equivalent_width` (returned −0.005 instead of
+  +1.88 Å), `redshift_lines`, `embed_band_power`, `embed_lick_indices`,
+  `embed_log_lambda`, `cross_correlate_rv`, `disentangle_sb2`,
+  `doppler_tomogram`, `classify_template_chi2`
+  and, on the reduction side, in the reference read by
+  `combine_spectra_arithmetic` (which silently returned the science flux
+  unchanged with a reversed reference), `remove_telluric_division` and
+  `response_from_standard`. Ascending input is unchanged.
+- `compare_normalisations` / `compare_smoothings` / `compare_snr_methods`
+  1.0.1 : work on a slim copy of the spectrum instead of deep-copying
+  the whole context (gigabytes in a reduction session).
+- `output_produces` declarations completed for `detect_lines`,
+  `vr_ratio`, `rotation_curve`, `redshift_lines`, `doppler_tomogram`,
+  `fit_keplerian_orbit`, `cross_correlate_rv`, `lomb_scargle`,
+  `disentangle_sb2`, the nebular trio and, on the reduction side, `match_lamp_lines`,
+  `wavelength_calibration_solar`, `fit_telluric_scaling`, `detect_trace`,
+  `extract_spectrum_boxcar`, `stack_spectra` ; a contract
+  test now checks that every written key is declared.
+
+### References
+
+- Corrected : `vr_ratio` Okazaki 1991 is PASJ 43, 75 (not A&A 246, 415) ;
+  `embed_spectrum` no longer credits Soubiran et al. 2016 (the PASTEL
+  catalogue) for the DCT ; `detect_lines` cites Press et al. 2007 §10.2
+  for three-point parabolic centroiding instead of "standard technique"
+   ; the air → vacuum
+  coefficients of `air_to_vacuum` are attributed to the Piskunov / VALD3
+  inverse fit (vacuum → air stays Morton 2000, with the Hα 6562.79 →
+  6564.603 Å acceptance value now tested) ; `detect_trace` cites
+  `scipy.signal.find_peaks`, which it actually calls, instead of
+  `center_of_mass` ; "standard technique" hand-waving replaced by Tody
+  1986 / 1993 in `wavelength_calibrate_polynomial`, Horne 1986 §2 in
+  `subtract_sky_2d`, Hinkle, Wallace & Livingston 2003 + Hardie 1962 in
+  `synth_telluric`, Bevington & Robinson 2003 in `clip_sigma`, Tody 1993 +
+  Horne 1986 in `merge_echelle_orders` ; `response_from_standard` drops
+  the unused Hayes & Latham citation and its docstring no longer promises
+  an airmass step that does not exist.
+- Added to bricks that had none : `equivalent_width`, `normalize_edges`,
+  `normalize_max`, `normalize_percentile`, `subtract_continuum`,
+  `snr_edge`, `snr_linear_fit`, `phase_fold`.
+- Still to verify (left in place, flagged in the audit) : Baldry 1999
+  (`embed_log_lambda`), Bu 2014 and Sánchez-Sáez 2021 (`embed_spectrum`),
+  Brault 1987 (`rv_precision_bouchy`), Teyssier 2015
+  (`validate_bess_header`).
+
+### Tests
+
+- First tests for the ten orphan bricks : `aperture_photometry`,
+  `simbad_query` / `gaia_query` / `vizier_query` (astroquery mocked),
+  `plot_dynamic_spectrum` / `plot_3d_surface_plotly` /
+  `plot_animation_plotly`, `export_hdf5`, `flux_calibrate_easyspec`,
+  `resample_flux_conserving`.
+- Literature acceptance values added : Bouchy 2001 eq. 6 closed form
+  (89.18 m/s), Lorentzian γ / FWHM / area, Voigt Olivero-Longbothum
+  FWHM, Lomb-Scargle FAP vs astropy, Morton 2000 Hα 6562.79 → 6564.603 Å,
+  Osterbrock [O III] table, Marsh-Horne spot position, slant round trip,
+  partial-overlap stacking, WCS Paper III log axis.
+- New MCP suites : parameter guard (12), tool extras (17), HTTP entry
+  point (6), rebinding / NAT64 / CGNAT cases, session cap and LRU.
+
 ## [0.6.0] — 2026-07-30
 
 Contributions from the SpecRelay / LineMill ecosystem audit

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

@@ -1,9 +1,9 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.6.0
+Version: 0.6.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: Documentation, https://docs.spectrokernel.io/
 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
@@ -54,9 +54,12 @@ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
+Requires-Dist: jsonschema>=4.0; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Requires-Dist: pyyaml>=6.0; extra == 'docs'
+Requires-Dist: zensical>=0.0.62; extra == 'docs'
 Provides-Extra: embedding-ml
 Requires-Dist: torch>=2.2; extra == 'embedding-ml'
 Provides-Extra: embedding-remote
@@ -178,6 +181,35 @@ transverse ones (`list_algorithms`, `describe_algorithm`, `get_algorithm_source`
 deploy the same `spectro-mcp` in HTTP mode on any container host (DigitalOcean
 App Platform, Fly.io, etc.). Local-stdio remains the recommended default.
 
+In `--http` mode the server refuses local filesystem paths, fetches URLs
+through an SSRF guard (no private addresses, no redirects, size and time
+caps), caps sessions and memory, and rate-limits clients. Two postures :
+
+- **Open** (the public demo server) : `SPECTRO_MCP_ALLOW_ANONYMOUS=1`. No
+  accounts, no key ; anyone adds `https://<host>/mcp` as a connector.
+- **Closed** : `SPECTRO_MCP_API_KEY=<secret>` ; clients send it in the
+  `X-API-Key` header (or `?api_key=` with `SPECTRO_MCP_ALLOW_KEY_IN_URL=1`).
+
+The server refuses to start in `--http` mode with neither. Configuration is
+by environment variable (none of these affect stdio mode) :
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SPECTRO_MCP_API_KEY` | unset | Closed posture : shared secret clients send in the `X-API-Key` header. |
+| `SPECTRO_MCP_ALLOW_ANONYMOUS` | unset | Open posture : `1` to start without a key (explicit opt-in). |
+| `SPECTRO_MCP_ALLOW_KEY_IN_URL` | unset | `1` also accepts the key as `?api_key=…` in the URL (for claude.ai / Claude Desktop connectors, which cannot set headers); the parameter is scrubbed before access logging. `Authorization: Bearer <key>` is always accepted. |
+| `SPECTRO_MCP_RATE_PER_MINUTE` | `0` (off) | Sliding-window request limit per API key (per client IP when auth is off). |
+| `SPECTRO_MCP_TRUSTED_PROXY` | unset | `1` behind a load balancer: trust `X-Forwarded-For` for the client IP. |
+| `SPECTRO_MCP_CORS_ORIGINS` | spectrokernel.io sites | Comma-separated browser origins allowed to call the server (`*` for any, `none` to disable). The `Mcp-Session-Id` header is exposed to browsers. |
+| `SPECTRO_MCP_MAX_SESSIONS` | `200` | Cap on live in-memory sessions; the least recently used one is evicted. |
+| `SPECTRO_MCP_MAX_PIXELS` | `32000000` | Refuse downloaded FITS files with more data elements than this (256 MB as float64); `0` disables. |
+| `SPECTRO_MCP_DOWNLOAD_BUDGET_S` | `120` | Wall-clock budget for one URL download (on top of the 256 MiB cap). |
+| `SPECTRO_MCP_MAX_CONCURRENT_DOWNLOADS` | `4` | Downloads allowed in flight at once. |
+| `SPECTRO_EMBED_ENDPOINT_ALLOW` | unset | Comma-separated hosts `embed_remote` may call with the server-side `SPECTRO_EMBED_API_KEY` (and bypass the SSRF guard for, e.g. an internal inference service). |
+| `SPECTRO_MCP_REDIS_URL`, `SPECTRO_MCP_SESSION_SECRET` | unset | Redis-backed sessions for multi-instance deployments (payloads are HMAC-signed with the secret). |
+| `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
+| `SENTRY_DSN` | unset | Error reporting. |
+
 ## Architecture
 
 ```
@@ -206,7 +238,7 @@ from the registry. Build it locally with:
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve     # live preview at http://127.0.0.1:8000
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
 ```
 
 Every algorithm declares its **provenance** — a `backend` (the library it leans on) and

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

@@ -92,6 +92,35 @@ transverse ones (`list_algorithms`, `describe_algorithm`, `get_algorithm_source`
 deploy the same `spectro-mcp` in HTTP mode on any container host (DigitalOcean
 App Platform, Fly.io, etc.). Local-stdio remains the recommended default.
 
+In `--http` mode the server refuses local filesystem paths, fetches URLs
+through an SSRF guard (no private addresses, no redirects, size and time
+caps), caps sessions and memory, and rate-limits clients. Two postures :
+
+- **Open** (the public demo server) : `SPECTRO_MCP_ALLOW_ANONYMOUS=1`. No
+  accounts, no key ; anyone adds `https://<host>/mcp` as a connector.
+- **Closed** : `SPECTRO_MCP_API_KEY=<secret>` ; clients send it in the
+  `X-API-Key` header (or `?api_key=` with `SPECTRO_MCP_ALLOW_KEY_IN_URL=1`).
+
+The server refuses to start in `--http` mode with neither. Configuration is
+by environment variable (none of these affect stdio mode) :
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SPECTRO_MCP_API_KEY` | unset | Closed posture : shared secret clients send in the `X-API-Key` header. |
+| `SPECTRO_MCP_ALLOW_ANONYMOUS` | unset | Open posture : `1` to start without a key (explicit opt-in). |
+| `SPECTRO_MCP_ALLOW_KEY_IN_URL` | unset | `1` also accepts the key as `?api_key=…` in the URL (for claude.ai / Claude Desktop connectors, which cannot set headers); the parameter is scrubbed before access logging. `Authorization: Bearer <key>` is always accepted. |
+| `SPECTRO_MCP_RATE_PER_MINUTE` | `0` (off) | Sliding-window request limit per API key (per client IP when auth is off). |
+| `SPECTRO_MCP_TRUSTED_PROXY` | unset | `1` behind a load balancer: trust `X-Forwarded-For` for the client IP. |
+| `SPECTRO_MCP_CORS_ORIGINS` | spectrokernel.io sites | Comma-separated browser origins allowed to call the server (`*` for any, `none` to disable). The `Mcp-Session-Id` header is exposed to browsers. |
+| `SPECTRO_MCP_MAX_SESSIONS` | `200` | Cap on live in-memory sessions; the least recently used one is evicted. |
+| `SPECTRO_MCP_MAX_PIXELS` | `32000000` | Refuse downloaded FITS files with more data elements than this (256 MB as float64); `0` disables. |
+| `SPECTRO_MCP_DOWNLOAD_BUDGET_S` | `120` | Wall-clock budget for one URL download (on top of the 256 MiB cap). |
+| `SPECTRO_MCP_MAX_CONCURRENT_DOWNLOADS` | `4` | Downloads allowed in flight at once. |
+| `SPECTRO_EMBED_ENDPOINT_ALLOW` | unset | Comma-separated hosts `embed_remote` may call with the server-side `SPECTRO_EMBED_API_KEY` (and bypass the SSRF guard for, e.g. an internal inference service). |
+| `SPECTRO_MCP_REDIS_URL`, `SPECTRO_MCP_SESSION_SECRET` | unset | Redis-backed sessions for multi-instance deployments (payloads are HMAC-signed with the secret). |
+| `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
+| `SENTRY_DSN` | unset | Error reporting. |
+
 ## Architecture
 
 ```
@@ -120,7 +149,7 @@ from the registry. Build it locally with:
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve     # live preview at http://127.0.0.1:8000
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
 ```
 
 Every algorithm declares its **provenance** — a `backend` (the library it leans on) and

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/concepts/algorithms.md

@@ -103,7 +103,7 @@ principle](../why.md#the-principle-we-do-not-reinvent). Every algorithm declares
 - its **`references`** - the literature for the method, or the wrapped library.
 
 Both are visible in `spectro describe <name>`, in the
-[catalogue](../catalogue.md), and in every MCP tool description. Nothing is a black box:
+[catalogue](../algorithms/index.md), and in every MCP tool description. Nothing is a black box:
 you can always see what an algorithm stands on and where the method comes from.
 
 ## Naming conventions

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/contributing.md

@@ -57,10 +57,10 @@ CI runs the same checks on every pull request; keep `main` green.
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve        # live preview at http://127.0.0.1:8000
-mkdocs build        # static build into site/
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
+python tools/docs/build.py                        # what CI runs: generators + strict build into site/
 ```
 
-The [algorithm catalogue](catalogue.md) page is *generated* from the registry at build
+The [algorithm catalogue](algorithms/index.md) page is *generated* from the registry at build
 time - you never edit it by hand. Add a docstring and metadata to your algorithm and the
 catalogue page documents it automatically.

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/getting-started.md

@@ -114,4 +114,4 @@ The agent now sees every algorithm as a tool. See [As an MCP server](usage/mcp.m
   catalogue](tutorials/discover-the-catalogue.md).
 - Understand the moving parts → [Concepts: architecture](concepts/architecture.md).
 - A guided, end-to-end analysis → [Tutorial: analyse a spectrum](tutorials/analyse-a-spectrum.md).
-- Browse everything available → [Algorithm catalogue](catalogue.md).
+- Browse everything available → [Algorithm catalogue](algorithms/index.md).

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/index.md

@@ -49,7 +49,7 @@ through MCP, you can do from a terminal, and vice-versa.
   your first analysis in five minutes.
 - :material-sitemap: **[Concepts](concepts/architecture.md)** - the architecture,
   the data types, the registry, the pipelines.
-- :material-book-open-variant: **[Algorithm catalogue](catalogue.md)** - every
+- :material-book-open-variant: **[Algorithm catalogue](algorithms/index.md)** - every
   algorithm, auto-generated from the code.
 - :material-school: **[Tutorials](tutorials/first-spectrum.md)** - from *"I captured a
   spectrum of a star, now what?"* all the way to writing your own algorithm.

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/reference.md

@@ -2,7 +2,7 @@
 
 This page is generated from the source docstrings by
 [mkdocstrings](https://mkdocstrings.github.io/). It documents the public Python API; for
-the *algorithms* themselves see the [catalogue](catalogue.md).
+the *algorithms* themselves see the [catalogue](algorithms/index.md).
 
 ## Data types
 

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/tutorials/discover-the-catalogue.md

@@ -106,7 +106,7 @@ Over [MCP](../usage/mcp.md), the discovery tools are `list_algorithms` and
 
 ## The full reference
 
-The [Algorithm catalogue](../catalogue.md) page lists **every** algorithm with its
+The [Algorithm catalogue](../algorithms/index.md) page lists **every** algorithm with its
 parameters, provenance and references, grouped by category. It is generated directly
 from the registry, so it is always in sync with the version you have installed.
 

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/tutorials/first-spectrum.md

@@ -149,4 +149,4 @@ checked, continuum normalised, lines identified. That is a genuine scientific re
   operation available, and how to inspect each one.
 - **A fuller, guided analysis** → [Analyse a spectrum](analyse-a-spectrum.md).
 - **Periodic targets** (Be stars, eclipsing binaries) → the `lomb_scargle` and
-  `phase_fold` algorithms in the [catalogue](../catalogue.md).
+  `phase_fold` algorithms in the [catalogue](../algorithms/index.md).

{spectro_kernel-0.6.0 → spectro_kernel-0.6.2}/docs/tutorials/long-slit-reduction.md

@@ -167,5 +167,5 @@ Every algorithm above follows the same kernel contract:
   `ctx.image.meta` (for 2-D) or `ctx.spectrum.meta` (for 1-D), and the
   per-step `metrics` are JSON-serialisable for later auditing.
 
-See [Algorithm catalogue](../catalogue.md) for the full parameter and
+See [Algorithm catalogue](../algorithms/index.md) for the full parameter and
 reference list of each brick.