Metadata-Version: 2.4
Name: casper-astro-tools
Version: 0.1.0
Summary: Open astronomy tools for AI agents and scripts: NASA ADS and arXiv, SIMBAD/NED/VizieR/Gaia and VO archives, and offline coordinate, time, unit, cosmology and observing calculators, as a Python library, a command line and an MCP server.
Author: Alireza Molaeinezhad, Nicholas Walton, Marco Riello, Eduardo González Solares, Leigh Smith, Giuseppe D'Ago, David Homan
Maintainer: Alireza Molaeinezhad
License: Apache-2.0
Project-URL: Homepage, https://gitlab.developers.cam.ac.uk/astronomy/camcead/casper-astro-tools
Project-URL: Repository, https://gitlab.developers.cam.ac.uk/astronomy/camcead/casper-astro-tools
Project-URL: Issues, https://gitlab.developers.cam.ac.uk/astronomy/camcead/casper-astro-tools/-/issues
Keywords: CASPER,astronomy,mcp,model-context-protocol,llm-tools,astropy,ads,arxiv,virtual-observatory,benchmark
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: astropy<9,>=7.0
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: mcp<3,>=2.3
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# CASPER Astro Tools (`casper-astro-tools`)

**Open astronomy tools for AI agents and scripts.** The open, public part of CASPER, the assistant platform of CAMCEAD at the Institute of Astronomy, University of Cambridge.

 46 read-only tools behind one calling protocol, usable as a Python library, a command line and a [Model Context Protocol](https://modelcontextprotocol.io) server (stdio and Streamable HTTP), with any model that can call functions:

| group | tools | needs |
|---|---|---|
| **Offline calculators** (17) | coordinate frames, proper motion, separation; time scales, sidereal time, barycentric corrections; units, magnitudes and fluxes, redshift and distance in a chosen cosmology, extinction law, spectral lines; observing sites, night timeline, target visibility and airmass, best nights, field-of-view membership | nothing, no network |
| **Literature** (10) | NASA ADS (search, one paper, references, citations, an object's literature, libraries) and arXiv (search, recent, one paper), with provenance on every result | arXiv: nothing. ADS: your own token in `ADS_API_TOKEN` |
| **Public archives** (19) | name resolution (CDS Sesame), SIMBAD, NED, VizieR, CDS cross-match, Gaia DR3, any Virtual Observatory TAP service and the VO registry, a table-driven search of SDSS, Pan-STARRS, Legacy Surveys, DESI, MAST, ESO, IRSA, HEASARC, CADC and ALMA, sky cut-out links | nothing; the public services must be reachable |

The [tool catalogue](docs/catalogue/index.md) has one page per tool (description, input schema, example call, example output); [`docs/tools.json`](docs/tools.json) is the same in machine-readable form. Both are generated from the code and a test fails if they drift.

Also in this repository: a [worked case study](examples/CASE_STUDY.md) (plan a night at La Palma, check proper motions, find the key papers; runs offline), and **CASPER AstroToolBench**, a seed benchmark of 73 offline tasks with checkable answers for models that use these tools ([bench/README.md](bench/README.md)).

## Install

```bash
pip install casper-astro-tools        # from PyPI once released; until then: pip install .
casper-astro-tools doctor             # checks the installation (no network)
```

Python 3.10 or newer (tested on 3.11). Dependencies: astropy, numpy, scipy, httpx, defusedxml, mcp.

## Use it

**Python**

```python
import casper_astro_tools as at

at.call("astro_convert_coordinates", lon="18h36m56.3364s", lat="+38:47:01.291", to_frame="galactic")["output"]["l_deg"]   # 67.448...
at.call("astro_cosmology", redshifts=[0.5])["results"][0]["luminosity_distance_mpc"]                                      # Planck18
at.call("gaia_source", source_id="4472832130942575872")                                                                   # needs the network
```

Every call returns a dict: `{"ok": true, ...}` or `{"ok": false, "error": "<code>", "message": "..."}`. Inside a running event loop use `await at.acall(...)`.

**Command line**

```bash
casper-astro-tools list                                     # the tools
casper-astro-tools describe astro_night_info                # schema and examples of one tool
casper-astro-tools call astro_night_info date=2026-11-12 site=wht
casper-astro-tools call resolve_name name="M 51" --offline  # answer from the bundled recordings, no network
```

**MCP server** (Claude Desktop, Claude Code, any MCP client)

```bash
casper-astro-tools serve                                    # stdio
casper-astro-tools serve --http --port 8765                 # Streamable HTTP at http://127.0.0.1:8765/mcp
```

```json
{ "mcpServers": { "casper-astro-tools": { "command": "casper-astro-tools", "args": ["serve"], "env": { "ADS_API_TOKEN": "your-ads-token" } } } }
```

Every tool is annotated read-only; the literature and archive tools are marked "open world" (they contact a public service), the calculators are not.

## Settings (environment variables, all optional)

| variable | meaning |
|---|---|
| `ADS_API_TOKEN` or `ADS_API_TOKEN_FILE` | your NASA ADS token ([create one](https://ui.adsabs.harvard.edu/user/settings/token)). Without it the ADS tools answer `ads_not_configured`; arXiv and the archives work. The token is never an argument, a result, a log line or an error. |
| `CASPER_ASTRO_TOOLS_CONTACT` | an e-mail address or URL added to the User-Agent sent to the public services (good manners for ADS, arXiv and the archives) |
| `CASPER_ASTRO_TOOLS_GROUPS` | which groups to offer: `calculators,literature,archives` (default all). `calculators` gives a server that never touches the network. |
| `CASPER_ASTRO_TOOLS_NETWORK=0` | refuse every tool that would contact a public service |
| `CASPER_ASTRO_TOOLS_ARCHIVE_RATE` | archive calls allowed per ten minutes (default 60) |

## What it does to be safe to give to a model

* **Read-only.** No tool writes, uploads, runs code or changes anything anywhere. ADQL queries must be a single `SELECT` (no comments, no semicolon, no write or sleep words outside quotes); `TOP` and `MAXREC` are forced to the row cap (500).
* **Allow-listed hosts.** The archive tools only contact hosts listed in `src/casper_astro_tools/archives/services.py` (https, port 443, no IP literals, every resolved address must be public; redirects are followed by hand and re-checked). A host found by a registry search is accepted for one hour in that process; no environment variable widens the list.
* **Bounded.** Row, byte, time and size caps on every call; arXiv is queued to one request per three seconds; ADS to 60 calls a minute.
* **Untrusted data is labelled.** Archive and literature results carry their provenance (service, address, query, time) and a notice that the content is third-party data, not instructions.
* **Offline by construction.** The calculators force astropy offline: nothing is downloaded, ever.

The HTTP server has **no login**: it binds to localhost. Put your own authenticating proxy in front before exposing it. See [SECURITY.md](SECURITY.md).

## Known limitations

* The hours-above-altitude figures count a 5-minute grid including both ends of the window, so they can exceed the true duration by one grid step (0.08 h).
* No dust map: `astro_extinction_law` takes E(B-V) from you. Cosmology distances ignore radiation (a 0.02 % effect at z = 0.5) and `absolute_magnitude_no_k_correction` has no K-correction by name.
* The Earth-orientation table is the one inside astropy; it is never refreshed over the network.
* Archive answers change when the archives do. The recordings under `src/casper_astro_tools/data/fixtures` are snapshots (archives 2026-10-22, arXiv and Gaia 2026-10-30), kept for tests and for the offline mode; the CDS services were unreachable from the recording host on 2026-10-30, so their snapshot is the older one.
* No ADS answer is recorded (ADS needs a personal token): the ADS examples in the catalogue come from an invented stand-in and say so on the page.

## Tests, regenerating the docs

```bash
pip install -e .[test]
pytest                                   # no network; about 40 s
python tools/gen_catalogue.py            # regenerate docs/catalogue and docs/tools.json (the test suite fails if you forget)
python bench/make_tasks.py               # regenerate the benchmark task files
python tools/record_fixtures.py out.json # re-record the public-service answers (network; read-only)
```

## Authors, citing, licence

Authors (all at the Institute of Astronomy, University of Cambridge; the first is the corresponding author): Alireza Molaeinezhad, Nicholas Walton, Marco Riello, Eduardo González Solares, Leigh Smith, Giuseppe D'Ago, David Homan.

Copyright 2026 CAMCEAD, Institute of Astronomy, University of Cambridge. Apache-2.0 ([LICENSE](LICENSE), [NOTICE](NOTICE)). Please cite via [CITATION.cff](CITATION.cff) (GitHub and GitLab render it as "Cite this repository"); until a software DOI exists, cite as:

> Molaeinezhad, A., Walton, N., Riello, M., González Solares, E., Smith, L., D'Ago, G., Homan, D. (2026). *CASPER Astro Tools: open astronomy tools for AI agents and scripts* (version 0.1.0) [Computer software]. Institute of Astronomy, University of Cambridge.

Security reports: see [SECURITY.md](SECURITY.md).

Related work: [ToolUniverse](https://arxiv.org/abs/2509.23426) (an open platform of biomedical tools behind one protocol). This package is a small, astronomy-specific, read-only counterpart; see [docs/DESIGN.md](docs/DESIGN.md) for how the two differ.

## Acknowledgements

This package is a client of public services and of open software. If you publish results obtained with it, please acknowledge what you used; the full sentences, citations and terms are in [docs/ACKNOWLEDGEMENTS.md](docs/ACKNOWLEDGEMENTS.md) (reviewed and accepted by the authors on 2026-11-01; where a service publishes different wording, use the service's). In short:

* *This research has made use of the SIMBAD database, operated at CDS, Strasbourg, France.* (Wenger et al. 2000, A&AS 143, 9)
* *This research has made use of the VizieR catalogue access tool, CDS, Strasbourg, France (DOI: 10.26093/cds/vizier).* (Ochsenbein et al. 2000, A&AS 143, 23)
* *This research has made use of the NASA/IPAC Extragalactic Database (NED), which is funded by the National Aeronautics and Space Administration and operated by the California Institute of Technology.*
* *This work has made use of data from the European Space Agency (ESA) mission Gaia (https://www.cosmos.esa.int/gaia), processed by the Gaia Data Processing and Analysis Consortium (DPAC, https://www.cosmos.esa.int/web/gaia/dpac/consortium).* (Gaia Collaboration 2016, 2023)
* *This research has made use of NASA's Astrophysics Data System Bibliographic Services.* ADS content is not redistributed by this package; the ADS examples are labelled stand-ins.
* *This research made use of Astropy (http://www.astropy.org), a community-developed core Python package for Astronomy (Astropy Collaboration, 2013, 2018, 2022).*
* arXiv: the API terms (one request per three seconds) are followed by the client; the arXiv metadata excerpts are shipped under arXiv's CC0 statement for metadata. Sesame, the CDS cross-match, hips2fits and the Virtual Observatory: see the acknowledgements page.

The short recorded excerpts of public answers under `src/casper_astro_tools/data/fixtures` each carry a mark naming the service and the date; see [NOTICE](NOTICE).
