Skip to content

Getting started

This page takes you from nothing to a working spectral analysis in a few minutes.

1. Install

spectro-kernel needs Python 3.11+. The recommended tool is uv, but plain pip works too.

git clone https://github.com/matthieulel/spectro-kernel
cd spectro-kernel
uv venv --python 3.12
uv pip install -e ".[dev,mcp]"

pip install spectro-kernel            # core library + CLI
pip install "spectro-kernel[mcp]"     # + the MCP server
pip install "spectro-kernel[all]"     # everything (catalogs, viz, storage, mcp)

Optional extras

The core install is deliberately light (astropy, numpy, scipy, pyyaml). Add what you need:

Extra Brings Unlocks
catalogs astroquery, pyvo simbad_query
viz plotly plot_spectrum_plotly, plot_overlay_plotly
mcp fastmcp the spectro-mcp server
storage boto3 S3 / DO Spaces object storage

An algorithm whose extra is missing simply does not register - the rest of the catalogue still loads.

2. Check it works

spectro info

spectro-kernel v0.1.0
  55 algorithms across 21 categories
  2 presets

3. Your first analysis - the library

import numpy as np
from spectro_kernel import WorkContext, run_algorithm
from spectro_kernel.types import Spectrum1D

# A synthetic spectrum: flat continuum + one emission line + noise.
wave = np.linspace(6400, 6700, 1500)
flux = 100 + 40 * np.exp(-0.5 * ((wave - 6562.8) / 3.4) ** 2)
flux += np.random.default_rng(0).normal(0, 1, wave.size)

ctx = WorkContext(spectrum=Spectrum1D(wave, flux))      # (1)!
run_algorithm("normalize_polynomial", ctx, {"order": 3})  # (2)!
run_algorithm("snr_der", ctx)
run_algorithm("fit_gaussian_line", ctx, {"line_center_angstrom": 6562.8})

print(f"SNR        = {ctx.metrics['snr_der']:.0f}")
print(f"H-alpha FWHM = {ctx.line_fits['6562.8'].fwhm_angstrom:.2f} Å")
  1. A WorkContext is the bag of data that flows through your analysis. You put a spectrum in; algorithms read from it and write results back into it.
  2. run_algorithm looks the algorithm up in the registry, runs it against the context, and records a step in ctx.history.

4. The same thing - the command line

No AI agent, no Python script needed:

spectro list --category line_fitting     # discover algorithms
spectro describe fit_gaussian_line       # see its parameters and references
spectro run snr_der --input obs.fits     # run one algorithm
spectro pipeline balmer_quick --input obs.fits   # run a whole preset

5. The same thing - for an AI agent

spectro-mcp --stdio

Point Claude Desktop at it (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "spectro-kernel": { "command": "spectro-mcp", "args": ["--stdio"] }
  }
}

The agent now sees every algorithm as a tool. See As an MCP server.

Where next