casper-astro-tools 0.1.0__tar.gz

casper_astro_tools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+# NOT ACTIVE until this directory is at the root of the public repository. Prepared 2026-10-30.
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip && pip install -e ".[test]"
+      - run: pytest
+      - run: python tools/gen_catalogue.py --check && python bench/make_tasks.py --check
+      - run: casper-astro-tools bench oracle
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install detect-secrets==1.5.0
+      - run: |
+          detect-secrets scan --exclude-files 'src/casper_astro_tools/data/fixtures/.*' > /tmp/secrets.json
+          python -c "import json,sys; d=json.load(open('/tmp/secrets.json')); n=sum(len(v) for v in d['results'].values()); print('findings:', n); sys.exit(1 if n else 0)"
+  build:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }

casper_astro_tools-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.env
+*.token

casper_astro_tools-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,48 @@
+# NOT ACTIVE until this file is at the root of the public repository. Prepared 2026-10-30; the owner activates it by publishing the repository (see the hosting repository's OWNER_ACTIONS).
+stages: [test, build]
+
+default:
+  image: python:3.12-slim
+  before_script:
+    - python -m pip install --upgrade pip
+    - pip install -e ".[test]"
+
+test:
+  stage: test
+  parallel:
+    matrix:
+      - PYVER: ["3.10", "3.11", "3.12"]
+  image: python:$PYVER-slim
+  script:
+    - pytest
+
+generated-files-are-current:
+  stage: test
+  script:
+    - python tools/gen_catalogue.py --check
+    - python bench/make_tasks.py --check
+
+secret-scan:
+  stage: test
+  script:
+    - pip install detect-secrets==1.5.0
+    - detect-secrets scan --exclude-files 'src/casper_astro_tools/data/fixtures/.*' > /tmp/secrets.json
+    - python -c "import json,sys; d=json.load(open('/tmp/secrets.json')); n=sum(len(v) for v in d['results'].values()); print('findings:', n); sys.exit(1 if n else 0)"
+
+oracle-baseline:
+  stage: test
+  script:
+    - casper-astro-tools bench oracle --out oracle.json
+  artifacts:
+    paths: [oracle.json]
+    expire_in: 30 days
+
+wheel:
+  stage: build
+  script:
+    - pip install build
+    - python -m build
+  artifacts:
+    paths: [dist/]
+  rules:
+    - if: $CI_COMMIT_TAG

casper_astro_tools-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (unreleased; prepared 2026-10-30)
+
+First public-ready version. Named CASPER Astro Tools to keep it with CASPER; copyright holder CAMCEAD, Institute of Astronomy, University of Cambridge (2026), Apache-2.0; seven authors recorded in CITATION.cff and pyproject.toml.
+
+* 46 read-only tools: 17 offline calculators, 10 literature tools (NASA ADS, arXiv), 19 archive tools (CDS, NED, Gaia, VO TAP, archive searches).
+* Python API (`call`, `acall`, `list_tools`), the `casper-astro-tools` command (`list`, `describe`, `call`, `serve`, `doctor`, `bench`) and an MCP server over stdio and Streamable HTTP.
+* Generated tool catalogue (`docs/catalogue`, `docs/tools.json`) with example calls and outputs; a test fails when it drifts from the code.
+* Offline mode: recorded answers of the public services under `src/casper_astro_tools/data/fixtures` replay without a network (tests, catalogue, case study, benchmark).
+* Case study (`examples/CASE_STUDY.md`, `examples/case_study.py`) with a model-agnostic tool-calling loop (`casper_astro_tools.agent`).
+* CASPER AstroToolBench v0.1: 73 offline tasks (25 single-tool, 24 multi-tool, 24 tool-selection among distractors), 8 live tasks kept separate, a scoring harness for any OpenAI-compatible endpoint, any MCP server or an answers file, and the deterministic oracle baseline.
+
+Differences from the tool servers this code was adapted from: no authentication or per-person policy layer (a hosting platform adds those); `astro_fov_check` takes an explicit `radius_deg` instead of instrument presets; the link-only archive entries were dropped; every user-visible string was made neutral; environment variables are `CASPER_ASTRO_TOOLS_*` and `ADS_API_TOKEN`.
+
+Fixed while preparing: the command line turned an arXiv identifier such as `2509.23426` into a number (arguments are now read according to the tool schema).
+
+Acknowledgements and recordings (2026-10-31): `docs/ACKNOWLEDGEMENTS.md`, NOTICE and README carry the acknowledgement and terms of the services; the recorded fixtures are shortened to excerpts (abstracts to 500 characters, pictures to their first bytes, error pages cut) and marked with `_meta` (services, date); `tests/test_fixture_marks.py` enforces the mark. Nothing was published before this version, so the names (distribution `casper-astro-tools`, import `casper_astro_tools`, command `casper-astro-tools`, variables `CASPER_ASTRO_TOOLS_*`) have no compatibility aliases.

casper_astro_tools-0.1.0/CITATION.cff

@@ -0,0 +1,43 @@
+cff-version: 1.2.0
+message: "If you use CASPER Astro Tools or CASPER AstroToolBench, please cite it as below. The DOI is added when the release is archived."
+title: "CASPER Astro Tools: open astronomy tools for AI agents and scripts"
+version: 0.1.0
+date-released: "2026-10-30"   # set to the real release date when tagging
+license: Apache-2.0
+type: software
+# ORCID iDs can be added to each author as   orcid: "https://orcid.org/0000-0000-0000-0000"
+authors:
+  - family-names: "Molaeinezhad"        # first and corresponding author
+    given-names: "Alireza"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "Walton"
+    given-names: "Nicholas"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "Riello"
+    given-names: "Marco"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "González Solares"
+    given-names: "Eduardo"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "Smith"
+    given-names: "Leigh"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "D'Ago"
+    given-names: "Giuseppe"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+  - family-names: "Homan"            
+    given-names: "David"
+    affiliation: "Institute of Astronomy, University of Cambridge"
+# doi: "10.5281/zenodo.XXXXXXX"          # add after the archive (Zenodo) record exists
+repository-code: "https://gitlab.developers.cam.ac.uk/astronomy/camcead/casper-astro-tools"
+keywords: [astronomy, MCP, tool use, benchmark, LLM agents, CASPER]
+abstract: "A standalone, read-only toolkit of 46 astronomy tools (literature, public archives, offline calculators) exposed as a Python API, a command line and a Model Context Protocol server, with a generated tool catalogue and a seed benchmark (CASPER AstroToolBench) for tool-using language models. It is the open, public part of CASPER, the assistant platform of CAMCEAD at the Institute of Astronomy, University of Cambridge."
+references:
+  - type: article
+    authors:
+      - family-names: "Gao"
+        given-names: "Shanghua"
+      - name: "et al. (11 authors on arXiv; complete the list from the record before publishing)"
+    title: "ToolUniverse: An open platform for democratizing AI scientists"
+    year: 2025
+    notes: "arXiv:2509.23426 (title and first author as returned by the arXiv API on 2026-10-30). Cited as related work."

casper_astro_tools-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+* `pip install -e .[test]` and `pytest` (no network needed).
+* A tool is added in one place, `src/casper_astro_tools/registry.py` (calculators and literature) or `src/casper_astro_tools/archives/specs.py` plus `archives/core.py` (archives). Give it a description with an example, an input schema with descriptions, examples that run, and a test against a known value or a recording.
+* Run `python tools/gen_catalogue.py` after any change to a tool; commit the regenerated `docs/`. Run `python bench/make_tasks.py` if you change a benchmark task.
+* New archive hosts go into `archives/services.py` only (https, port 443). New recordings: `python tools/record_fixtures.py` and review the diff (public data only, no credentials; the recorder cuts and marks the file, and `tests/test_fixture_marks.py` fails for a fixture without its mark of service and date).
+* The package is part of CASPER by name but must stay free of the host's operational detail (project names, hosts, paths, accounts, secrets): `tests/test_hygiene.py` enforces it.

casper_astro_tools-0.1.0/LICENSE

@@ -0,0 +1,198 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,

casper_astro_tools-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE NOTICE README.md CHANGELOG.md CITATION.cff SECURITY.md CONTRIBUTING.md .gitignore .gitlab-ci.yml
+recursive-include docs *
+recursive-include examples *
+recursive-include bench *
+recursive-include tools *.py
+recursive-include tests *.py *.json *.xml
+recursive-include .github *.yml
+prune **/__pycache__
+global-exclude *.pyc

casper_astro_tools-0.1.0/NOTICE

@@ -0,0 +1,38 @@
+CASPER Astro Tools
+Copyright 2026 CAMCEAD, Institute of Astronomy, University of Cambridge
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+CASPER Astro Tools is the open, public part of CASPER, the assistant platform of CAMCEAD at the
+Institute of Astronomy, University of Cambridge. It contains code adapted from astronomy tool servers
+developed at the Institute of Astronomy, released here under the Apache License 2.0.
+
+Third-party services and data
+-----------------------------
+The package is a client of public services: NASA ADS, arXiv, CDS (SIMBAD, VizieR, Sesame, X-Match,
+hips2fits), NED, IRSA, ESA Gaia, MAST, ESO, HEASARC, CADC, ALMA, SDSS, NOIRLab Astro Data Lab and the
+IVOA registry. Their data and terms are theirs. If you publish results obtained through this package,
+acknowledge the services you used as each of them asks; the acknowledgement sentences, citations and
+the terms are in docs/ACKNOWLEDGEMENTS.md and docs/DATA_AND_TERMS.md. In short:
+
+  * This research has made use of the SIMBAD database, operated at CDS, Strasbourg, France.
+  * This research has made use of the VizieR catalogue access tool, CDS, Strasbourg, France
+    (DOI: 10.26093/cds/vizier).
+  * 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).
+  * This research has made use of NASA's Astrophysics Data System Bibliographic Services.
+  * This research made use of Astropy (http://www.astropy.org), a community-developed core Python
+    package for Astronomy (Astropy Collaboration, 2013, 2018, 2022).
+  * arXiv, Sesame, X-Match, hips2fits and the Virtual Observatory: see docs/ACKNOWLEDGEMENTS.md
+    (reviewed and accepted by the authors on 2026-11-01; where a service publishes different wording, use the service's).
+
+Recorded excerpts
+-----------------
+The files under src/casper_astro_tools/data/fixtures are short excerpts of answers of the public
+services, recorded read-only on the date written in each file's "_meta" mark and kept for tests,
+documentation and offline replay. The content belongs to the services. NASA ADS content is NOT
+redistributed: the ADS examples are invented stand-ins labelled "[synthetic]". The files under
+tests/fixtures are hand-written, synthetic and marked as such.

casper_astro_tools-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+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).