spectro-kernel

A shared catalogue of astronomical spectroscopy algorithms — composable into reproducible pipelines, usable as a Python library, a CLI, or an MCP server.

spectro-kernel is the common foundation for every spectroscopy application: FITS reading/writing, continuum normalisation, SNR, line detection and fitting, smoothing, resampling, barycentric correction, periodograms, exports — implemented once, tested once, and reused everywhere instead of being re-coded (subtly differently) in each project.

It is designed to be the substrate of any future spectroscopy app — a stellar reduction pipeline, a visualisation dashboard, a campaign-collection backend — and it works with or without an AI agent:

• Without an agent — import spectro_kernel in any Python project, or use the spectro command-line tool.
• With an agent — run the MCP server (spectro_mcp); Claude and other agents see the same catalogue as discoverable tools. Functional parity between the two access paths is an invariant.

Install

pip install spectro-kernel              # core library + CLI
pip install spectro-kernel[catalogs]    # + SIMBAD / VizieR queries
pip install spectro-kernel[mcp]         # + MCP server
pip install spectro-kernel[all]         # everything

From source (recommended for development):

uv venv --python 3.12
uv pip install -e ".[dev,mcp]"

Quickstart — library

from spectro_kernel import WorkContext, run_algorithm
from spectro_kernel.io import read_fits

ctx = WorkContext(spectrum=read_fits("obs.fits"))
run_algorithm("normalize_polynomial", ctx, {"order": 3})
run_algorithm("snr_der", ctx)
print(ctx.metrics["snr_der"])

Or compose a pipeline:

from spectro_kernel import PipelineBuilder

pipeline = (
    PipelineBuilder()
    .add("normalize_polynomial", order=3)
    .add("snr_der")
    .add("fit_gaussian_line", line_center_angstrom=6562.8, window_angstrom=30)
    .build()
)
result = pipeline.execute(ctx)

Quickstart — CLI (no AI agent needed)

spectro list                              # discover the catalogue
spectro describe fit_gaussian_line        # see params, inputs, outputs
spectro run snr_der --input obs.fits      # run one algorithm
spectro pipeline balmer_quick --input obs.fits   # run a preset pipeline

Quickstart — MCP server (for AI agents)

Local-first. After pip install "spectro-kernel[mcp]", point Claude Desktop at the binary — no server to run, no URL, no API key:

// ~/Library/Application Support/Claude/claude_desktop_config.json   (macOS)
{
  "mcpServers": {
    "spectro": { "command": "spectro-mcp" }
  }
}

Restart Claude Desktop — every catalogue algorithm appears as a tool, plus the transverse ones (list_algorithms, describe_algorithm, get_algorithm_source, run_preset, …).

Cloud option. For claude.ai (web), shared access, or non-Python users: 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) :

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 collection (pip install spectro-kernel-recipes). See the Recipes documentation.

Architecture

spectro_kernel/        importable Python package — the catalogue
  types/               Spectrum1D, WorkContext, ProcessingStep, ...
  registry.py          @register_algorithm + discovery API
  base.py              BaseAlgorithm + AlgorithmOutput
  pipeline.py          Pipeline + PipelineBuilder
  io/                  FITS / ASCII readers and writers
  algorithms/          the catalogue, one file per algorithm
  presets/             YAML pipeline recipes
  cli.py               the `spectro` command

spectro_mcp/           MCP server wrapping the same catalogue

Add an algorithm = one Python file + one test. No change to the core. See CONTRIBUTING.md.

Documentation

The full documentation site (built with MkDocs Material) lives in docs/ and covers: Why spectro-kernel? (what it adds on top of astropy/specutils), the concepts with diagrams, a guide per access path, tutorials, and an algorithm catalogue generated from the registry. Build it locally with:

uv pip install -e ".[docs,all]"
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 literature references — visible in spectro describe <name> and in the docs.

Repository layout

Two things in this repo are documentation-facing; do not confuse them:

In short: edit docs/ for documentation, edit website/ for the landing page, ignore site/.

Status

v0.1.0 — alpha. API unstable until v1.0.0. See CHANGELOG.md for release notes.

License

MIT — see LICENSE.