Metadata-Version: 2.4
Name: spectro-kernel
Version: 0.3.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://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: matthieulel
License: MIT
License-File: LICENSE
Keywords: astronomy,fits,mcp,pipeline,spectroscopy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: astropy>=6.0
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.12
Requires-Dist: specutils>=1.13
Provides-Extra: all
Requires-Dist: astroquery>=0.4.7; extra == 'all'
Requires-Dist: astroscrappy>=1.1; extra == 'all'
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: ccdproc>=2.4; extra == 'all'
Requires-Dist: dust-extinction>=1.5; extra == 'all'
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'
Provides-Extra: catalogs
Requires-Dist: astroquery>=0.4.7; extra == 'catalogs'
Requires-Dist: pyvo>=1.5; extra == 'catalogs'
Provides-Extra: dev
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: 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'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'mcp'
Provides-Extra: monitoring
Requires-Dist: sentry-sdk>=2.0; extra == 'monitoring'
Provides-Extra: reduction
Requires-Dist: astroscrappy>=1.1; extra == 'reduction'
Requires-Dist: ccdproc>=2.4; extra == 'reduction'
Requires-Dist: dust-extinction>=1.5; extra == 'reduction'
Requires-Dist: easyspec>=1.0; extra == 'reduction'
Requires-Dist: emcee>=3.1; extra == 'reduction'
Requires-Dist: matplotlib>=3.8; extra == 'reduction'
Requires-Dist: photutils>=2.0; extra == 'reduction'
Provides-Extra: storage
Requires-Dist: boto3>=1.34; extra == 'storage'
Requires-Dist: h5py>=3.10; extra == 'storage'
Provides-Extra: viz
Requires-Dist: plotly>=5.20; extra == 'viz'
Description-Content-Type: text/markdown

# 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

```bash
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):

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

## Quickstart — library

```python
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:

```python
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)

```bash
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:

```jsonc
// ~/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.

## 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](CONTRIBUTING.md).

## Documentation

The full documentation site (built with MkDocs Material) lives in [docs/](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:

```bash
uv pip install -e ".[docs,all]"
mkdocs 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:

| Path | What it is | Tracked? |
|------|------------|----------|
| `src/spectro_kernel/`, `src/spectro_mcp/` | The Python packages — the actual product. | yes |
| `tests/` | The test suite. | yes |
| `docs/` | **The documentation** — MkDocs Material source (Markdown). The technical site: concepts, guides, tutorials, API reference. | yes |
| `website/` | **The public landing page** — a standalone React + Vite app, deployable to Netlify. Separate from `docs/`; see [website/README.md](website/README.md). | yes |
| `site/`, `website/dist/`, `website/node_modules/` | Generated build output / dependencies. Build cruft — **git-ignored**, never edited by hand. | no |

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](CHANGELOG.md) for
release notes.

## License

MIT — see [LICENSE](LICENSE).
