casper-astro-tools 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- casper_astro_tools/__init__.py +16 -0
- casper_astro_tools/__main__.py +3 -0
- casper_astro_tools/_offline.py +28 -0
- casper_astro_tools/ads.py +242 -0
- casper_astro_tools/agent.py +195 -0
- casper_astro_tools/api.py +62 -0
- casper_astro_tools/archives/core.py +567 -0
- casper_astro_tools/archives/safety.py +392 -0
- casper_astro_tools/archives/services.py +142 -0
- casper_astro_tools/archives/specs.py +138 -0
- casper_astro_tools/archives/tables.py +152 -0
- casper_astro_tools/archives/upstream.py +116 -0
- casper_astro_tools/arxiv.py +174 -0
- casper_astro_tools/bench.py +359 -0
- casper_astro_tools/cli.py +156 -0
- casper_astro_tools/common.py +138 -0
- casper_astro_tools/coords.py +195 -0
- casper_astro_tools/data/bench/astrotoolbench_live.jsonl +9 -0
- casper_astro_tools/data/bench/astrotoolbench_offline.jsonl +74 -0
- casper_astro_tools/data/fixtures/archives_2026-10-22.json +183 -0
- casper_astro_tools/data/fixtures/live_2026-10-30.json +102 -0
- casper_astro_tools/lines.py +97 -0
- casper_astro_tools/lit_common.py +78 -0
- casper_astro_tools/observing.py +375 -0
- casper_astro_tools/physics.py +290 -0
- casper_astro_tools/py.typed +0 -0
- casper_astro_tools/registry.py +307 -0
- casper_astro_tools/runtime.py +84 -0
- casper_astro_tools/server.py +58 -0
- casper_astro_tools/sites.py +49 -0
- casper_astro_tools/testing.py +165 -0
- casper_astro_tools/timescales.py +123 -0
- casper_astro_tools-0.1.0.dist-info/METADATA +154 -0
- casper_astro_tools-0.1.0.dist-info/RECORD +39 -0
- casper_astro_tools-0.1.0.dist-info/WHEEL +5 -0
- casper_astro_tools-0.1.0.dist-info/entry_points.txt +2 -0
- casper_astro_tools-0.1.0.dist-info/licenses/LICENSE +198 -0
- casper_astro_tools-0.1.0.dist-info/licenses/NOTICE +38 -0
- casper_astro_tools-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""casper-astro-tools: open astronomy tools (literature, archives, offline calculators) behind one calling protocol.
|
|
2
|
+
|
|
3
|
+
Python API: `from casper_astro_tools import call, list_tools`. Command line: `casper-astro-tools`. MCP server: `casper-astro-tools serve`.
|
|
4
|
+
"""
|
|
5
|
+
__version__ = "0.1.0"
|
|
6
|
+
__all__ = ["__version__", "call", "call_sync", "acall", "list_tools", "tool_names", "Runtime"]
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def __getattr__(name): # lazy: importing the package must not import astropy
|
|
10
|
+
if name in ("call", "call_sync", "acall", "list_tools", "tool_names"):
|
|
11
|
+
from . import api
|
|
12
|
+
return getattr(api, name)
|
|
13
|
+
if name == "Runtime":
|
|
14
|
+
from .runtime import Runtime
|
|
15
|
+
return Runtime
|
|
16
|
+
raise AttributeError(name)
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""Makes astropy strictly OFFLINE before anything else imports it (the calculators must never reach the network; no data leaves your machine).
|
|
3
|
+
|
|
4
|
+
* `allow_internet = False`: any astropy call that would download a file (site lists, IERS tables, ephemerides, dust maps) raises instead.
|
|
5
|
+
* IERS: the Earth-orientation table that ships inside the astropy-iers-data package is used; it is never refreshed over the network. Outside its range astropy falls back to a degraded
|
|
6
|
+
prediction (error well below one second of time, about 10 milliarcseconds of pole), which is far finer than anything these tools promise.
|
|
7
|
+
* Solar-system ephemeris: the built-in analytic one (ERFA), good to a few kilometres for the Earth/Sun and to a few arcseconds for the Moon: no kernel download.
|
|
8
|
+
Import this module first (every other module of the package does).
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import warnings
|
|
13
|
+
|
|
14
|
+
from astropy.utils import iers
|
|
15
|
+
from astropy.utils.data import conf as _data_conf
|
|
16
|
+
from astropy.coordinates import solar_system_ephemeris
|
|
17
|
+
|
|
18
|
+
_data_conf.allow_internet = False
|
|
19
|
+
iers.conf.auto_download = False
|
|
20
|
+
iers.conf.auto_max_age = None
|
|
21
|
+
iers.conf.iers_degraded_accuracy = "ignore"
|
|
22
|
+
solar_system_ephemeris.set("builtin")
|
|
23
|
+
|
|
24
|
+
# ERFA warns "dubious year" for dates far from the leap-second table; the tools report their own assumption instead.
|
|
25
|
+
warnings.filterwarnings("ignore", message=".*dubious year.*")
|
|
26
|
+
warnings.filterwarnings("ignore", category=iers.IERSStaleWarning)
|
|
27
|
+
warnings.filterwarnings("ignore", message=".*distance overridden.*")
|
|
28
|
+
warnings.filterwarnings("ignore", message=".*Tcmb0.*")
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""NASA ADS (api.adsabs.harvard.edu/v1): search, one paper, references, citations, objects, libraries.
|
|
3
|
+
|
|
4
|
+
THE TOKEN. It is read from the environment variable named ADS_API_TOKEN, or from the file whose path is in ADS_API_TOKEN_FILE (for example a mounted secret). It is read at the moment of a call,
|
|
5
|
+
used only in the Authorization header of the HTTPS request to ADS, and never written to a result, an error, a log line or a file. Without a token every ADS tool answers 'ads_not_configured'
|
|
6
|
+
and the arXiv tools are unaffected. This package never accepts a token as a tool argument.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
import re
|
|
12
|
+
from typing import Any, Callable
|
|
13
|
+
from urllib.parse import quote
|
|
14
|
+
|
|
15
|
+
import httpx
|
|
16
|
+
|
|
17
|
+
from .common import MAX_QUERY, ToolError, choice, clean_round, integer, now_utc_iso, ok, text
|
|
18
|
+
from .lit_common import CAUTION, USER_AGENT, Budget, ads_abs_url, provenance
|
|
19
|
+
|
|
20
|
+
ADS_BASE = "https://api.adsabs.harvard.edu/v1"
|
|
21
|
+
BIBCODE = re.compile(r"^[0-9]{4}[A-Za-z0-9.&]{15}$")
|
|
22
|
+
LIBRARY_ID = re.compile(r"^[A-Za-z0-9_-]{6,64}$")
|
|
23
|
+
SORTS = ("date desc", "date asc", "citation_count desc", "read_count desc", "score desc")
|
|
24
|
+
_TOKEN_OK = re.compile(r"^[A-Za-z0-9_.\-]{20,200}$")
|
|
25
|
+
MAX_BYTES = 6_000_000
|
|
26
|
+
_FIELDS = "bibcode,title,author,first_author,year,pubdate,pub,doi,identifier,citation_count,read_count,doctype,property,keyword,volume,page"
|
|
27
|
+
_FIELDS_FULL = _FIELDS + ",abstract,aff,orcid_pub,bibstem,issue,page_count,comment"
|
|
28
|
+
_VAL_BAD = re.compile(r'["\\\x00-\x1f\x7f]')
|
|
29
|
+
|
|
30
|
+
NOT_CONFIGURED = {"ok": False, "error": "ads_not_configured",
|
|
31
|
+
"message": "ADS is not configured (no ADS API token was found in the environment variable ADS_API_TOKEN or in the file named by ADS_API_TOKEN_FILE). The arXiv tools (arxiv_search, arxiv_recent, arxiv_get_paper) work without one; "
|
|
32
|
+
"create a free token in your ADS account settings (https://ui.adsabs.harvard.edu/user/settings/token) and export it as ADS_API_TOKEN."}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def load_token(environ: dict | None = None) -> str | None:
|
|
36
|
+
"""The ADS token from ADS_API_TOKEN or the file named in ADS_API_TOKEN_FILE; None when absent or malformed. Never logs or returns the value."""
|
|
37
|
+
env = os.environ if environ is None else environ
|
|
38
|
+
tok = (env.get("ADS_API_TOKEN") or "").strip()
|
|
39
|
+
if not tok:
|
|
40
|
+
path = (env.get("ADS_API_TOKEN_FILE") or "").strip()
|
|
41
|
+
if path:
|
|
42
|
+
try:
|
|
43
|
+
with open(path, "r", encoding="utf-8") as fh:
|
|
44
|
+
tok = fh.read(4096).strip()
|
|
45
|
+
except OSError:
|
|
46
|
+
tok = ""
|
|
47
|
+
return tok if tok and _TOKEN_OK.match(tok) else None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _val(value: Any, name: str, max_len: int = 120) -> str:
|
|
51
|
+
v = text(value, name, max_len)
|
|
52
|
+
if _VAL_BAD.search(v):
|
|
53
|
+
v = _VAL_BAD.sub(" ", v).strip()
|
|
54
|
+
if not v:
|
|
55
|
+
raise ToolError("bad_input", f"{name} is empty after removing quotes and control characters")
|
|
56
|
+
return v
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def bibcode_of(value: Any, name: str = "bibcode") -> str:
|
|
60
|
+
b = text(value, name, 200)
|
|
61
|
+
m = re.search(r"abs/([^/\s?#]+)", b)
|
|
62
|
+
if m:
|
|
63
|
+
from urllib.parse import unquote
|
|
64
|
+
b = unquote(m.group(1))
|
|
65
|
+
if not BIBCODE.match(b):
|
|
66
|
+
raise ToolError("bad_input", f"{name} {b[:30]!r} is not an ADS bibcode (19 characters such as '2019A&A...628A..94G'); search first with ads_search")
|
|
67
|
+
return b
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def build_query(query: Any = None, author: Any = None, first_author: Any = None, title: Any = None, abstract: Any = None, obj: Any = None, bibcode: Any = None,
|
|
71
|
+
year_from: Any = None, year_to: Any = None, refereed_only: bool = False) -> str:
|
|
72
|
+
parts: list[str] = []
|
|
73
|
+
if query:
|
|
74
|
+
parts.append("(" + text(query, "query", MAX_QUERY) + ")")
|
|
75
|
+
if author:
|
|
76
|
+
parts.append(f'author:"{_val(author, "author")}"')
|
|
77
|
+
if first_author:
|
|
78
|
+
parts.append(f'first_author:"{_val(first_author, "first_author")}"')
|
|
79
|
+
if title:
|
|
80
|
+
parts.append(f'title:"{_val(title, "title", 200)}"')
|
|
81
|
+
if abstract:
|
|
82
|
+
parts.append(f'abs:"{_val(abstract, "abstract", 200)}"')
|
|
83
|
+
if obj:
|
|
84
|
+
parts.append(f'object:"{_val(obj, "object", 80)}"')
|
|
85
|
+
if bibcode:
|
|
86
|
+
parts.append(f"bibcode:{bibcode_of(bibcode)}")
|
|
87
|
+
if year_from is not None or year_to is not None:
|
|
88
|
+
lo = integer(year_from, "year_from", 1600, 2100) if year_from is not None else 1600
|
|
89
|
+
hi = integer(year_to, "year_to", 1600, 2100) if year_to is not None else 2100
|
|
90
|
+
if hi < lo:
|
|
91
|
+
raise ToolError("bad_input", "year_to is before year_from")
|
|
92
|
+
parts.append(f"year:[{lo} TO {hi}]")
|
|
93
|
+
if refereed_only:
|
|
94
|
+
parts.append("property:refereed")
|
|
95
|
+
if not parts:
|
|
96
|
+
raise ToolError("bad_input", "give at least one of query, author, first_author, title, abstract, object, bibcode, year_from/year_to")
|
|
97
|
+
q = " AND ".join(parts)
|
|
98
|
+
if len(q) > 900:
|
|
99
|
+
raise ToolError("too_long", "the combined ADS query is too long; shorten it")
|
|
100
|
+
return q
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def normalise(doc: dict, with_abstract: bool = False, abstract_chars: int = 700) -> dict:
|
|
104
|
+
def first(x: Any) -> Any:
|
|
105
|
+
return x[0] if isinstance(x, list) and x else x
|
|
106
|
+
|
|
107
|
+
authors = list(doc.get("author") or [])
|
|
108
|
+
ids = [i for i in (doc.get("identifier") or []) if isinstance(i, str)]
|
|
109
|
+
arx = next((i.split(":", 1)[1] for i in ids if i.lower().startswith("arxiv:")), None)
|
|
110
|
+
props = [str(p).upper() for p in (doc.get("property") or [])]
|
|
111
|
+
bib = str(doc.get("bibcode") or "")
|
|
112
|
+
year = doc.get("year")
|
|
113
|
+
out = {"bibcode": bib, "title": first(doc.get("title")) or "", "authors": authors[:8], "n_authors": len(authors), "first_author": doc.get("first_author") or (authors[0] if authors else None),
|
|
114
|
+
"year": int(year) if str(year or "").isdigit() else None, "pubdate": doc.get("pubdate"), "venue": doc.get("pub"), "volume": doc.get("volume"), "page": first(doc.get("page")),
|
|
115
|
+
"doi": first(doc.get("doi")), "arxiv_id": arx, "citation_count": doc.get("citation_count"), "read_count": doc.get("read_count"), "doctype": doc.get("doctype"),
|
|
116
|
+
"refereed": "REFEREED" in props, "open_access": "OPENACCESS" in props or "EPRINT_OPENACCESS" in props, "ads_url": ads_abs_url(bib) if bib else None,
|
|
117
|
+
"arxiv_url": f"https://arxiv.org/abs/{arx}" if arx else None, "doi_url": f"https://doi.org/{first(doc.get('doi'))}" if doc.get("doi") else None,
|
|
118
|
+
"keywords": list(doc.get("keyword") or [])[:12]}
|
|
119
|
+
if with_abstract:
|
|
120
|
+
ab = doc.get("abstract") or ""
|
|
121
|
+
out["abstract"] = ab if abstract_chars <= 0 else (ab[:abstract_chars] + ("..." if len(ab) > abstract_chars else ""))
|
|
122
|
+
return out
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
class AdsClient:
|
|
126
|
+
def __init__(self, http: httpx.AsyncClient | None = None, *, base: str = ADS_BASE, token_loader: Callable[[], str | None] = load_token, budget: Budget | None = None):
|
|
127
|
+
self.http = http or httpx.AsyncClient(timeout=httpx.Timeout(20.0, connect=8.0), headers={"User-Agent": USER_AGENT}, follow_redirects=False)
|
|
128
|
+
self.base, self._token, self.budget = base.rstrip("/"), token_loader, budget or Budget(60)
|
|
129
|
+
|
|
130
|
+
def configured(self) -> bool:
|
|
131
|
+
return self._token() is not None
|
|
132
|
+
|
|
133
|
+
async def _get(self, path: str, params: dict) -> tuple[dict, httpx.Response]:
|
|
134
|
+
tok = self._token()
|
|
135
|
+
if tok is None:
|
|
136
|
+
raise ToolError("ads_not_configured", NOT_CONFIGURED["message"])
|
|
137
|
+
if not self.budget.take():
|
|
138
|
+
raise ToolError("rate_limited", "this server's own ADS budget (60 calls a minute) is used up; wait a minute and try again")
|
|
139
|
+
try:
|
|
140
|
+
r = await self.http.get(f"{self.base}{path}", params=params, headers={"Authorization": f"Bearer {tok}", "Accept": "application/json", "User-Agent": USER_AGENT})
|
|
141
|
+
except httpx.HTTPError as exc:
|
|
142
|
+
raise ToolError("ads_unreachable", f"NASA ADS could not be reached ({type(exc).__name__}); try again later") from None
|
|
143
|
+
if r.status_code in (401, 403):
|
|
144
|
+
raise ToolError("ads_unauthorised", "ADS refused the token (expired or revoked). Create a new token in your ADS account settings and export it as ADS_API_TOKEN.")
|
|
145
|
+
if r.status_code == 429:
|
|
146
|
+
raise ToolError("ads_rate_limited", "ADS says the daily or per-second allowance is used up" + (f" (resets at {r.headers['X-RateLimit-Reset']})" if r.headers.get("X-RateLimit-Reset") else "") + "; try again later")
|
|
147
|
+
if r.status_code == 404:
|
|
148
|
+
raise ToolError("not_found", "ADS has nothing at that address (unknown library id or bibcode)")
|
|
149
|
+
if r.status_code >= 500:
|
|
150
|
+
raise ToolError("ads_unavailable", f"NASA ADS is unavailable at the moment (HTTP {r.status_code}); try again later")
|
|
151
|
+
if r.status_code != 200:
|
|
152
|
+
raise ToolError("ads_error", f"ADS answered HTTP {r.status_code}")
|
|
153
|
+
if len(r.content) > MAX_BYTES:
|
|
154
|
+
raise ToolError("too_large", "ADS returned an unexpectedly large answer; narrow the query")
|
|
155
|
+
try:
|
|
156
|
+
return r.json(), r
|
|
157
|
+
except ValueError:
|
|
158
|
+
raise ToolError("ads_error", "ADS returned something that is not JSON") from None
|
|
159
|
+
|
|
160
|
+
async def search(self, q: str, rows: int, sort: str, start: int = 0, full: bool = False, abstract_chars: int = 700) -> dict:
|
|
161
|
+
body, r = await self._get("/search/query", {"q": q, "fl": _FIELDS_FULL if full else _FIELDS + ",abstract", "rows": rows, "start": start, "sort": sort})
|
|
162
|
+
resp = body.get("response") or {}
|
|
163
|
+
docs = resp.get("docs") or []
|
|
164
|
+
return {"num_found": int(resp.get("numFound") or 0), "docs": [normalise(d, with_abstract=full or abstract_chars > 0, abstract_chars=abstract_chars) for d in docs],
|
|
165
|
+
"remaining": r.headers.get("X-RateLimit-Remaining")}
|
|
166
|
+
|
|
167
|
+
def _prov(self, q: str, endpoint: str, res: dict, rows: int, sort: str) -> dict:
|
|
168
|
+
return provenance("NASA ADS (api.adsabs.harvard.edu/v1)", endpoint=endpoint, query_sent=q, sort=sort, rows_requested=rows, num_found=res["num_found"],
|
|
169
|
+
ads_web_url="https://ui.adsabs.harvard.edu/search/q=" + quote(q, safe=""), rate_limit_remaining=res.get("remaining"))
|
|
170
|
+
|
|
171
|
+
async def tool_search(self, query=None, author=None, first_author=None, title=None, abstract=None, object=None, bibcode=None, year_from=None, year_to=None, # noqa: A002
|
|
172
|
+
refereed_only=False, rows=10, sort="citation_count desc", include_abstract=False) -> dict:
|
|
173
|
+
if not self.configured():
|
|
174
|
+
return dict(NOT_CONFIGURED)
|
|
175
|
+
q = build_query(query, author, first_author, title, abstract, object, bibcode, year_from, year_to, bool(refereed_only))
|
|
176
|
+
n, s = integer(rows, "rows", 1, 50), choice(sort, "sort", SORTS, "citation_count desc")
|
|
177
|
+
res = await self.search(q, n, s, abstract_chars=500 if include_abstract else 0)
|
|
178
|
+
return ok({"count": len(res["docs"]), "num_found": res["num_found"], "papers": res["docs"], "provenance": self._prov(q, "search/query", res, n, s), "caution": CAUTION})
|
|
179
|
+
|
|
180
|
+
async def tool_get_paper(self, bibcode) -> dict:
|
|
181
|
+
if not self.configured():
|
|
182
|
+
return dict(NOT_CONFIGURED)
|
|
183
|
+
b = bibcode_of(bibcode)
|
|
184
|
+
res = await self.search(f"bibcode:{b}", 1, "date desc", full=True, abstract_chars=0)
|
|
185
|
+
if not res["docs"]:
|
|
186
|
+
raise ToolError("not_found", f"ADS has no record with bibcode {b}; check it with ads_search")
|
|
187
|
+
return ok({"paper": res["docs"][0], "provenance": self._prov(f"bibcode:{b}", "search/query", res, 1, "date desc"), "caution": CAUTION})
|
|
188
|
+
|
|
189
|
+
async def _related(self, op: str, bibcode, rows, sort, year_from, year_to, refereed_only) -> dict:
|
|
190
|
+
if not self.configured():
|
|
191
|
+
return dict(NOT_CONFIGURED)
|
|
192
|
+
b = bibcode_of(bibcode)
|
|
193
|
+
n, s = integer(rows, "rows", 1, 50), choice(sort, "sort", SORTS, "citation_count desc")
|
|
194
|
+
extra = build_query(None, None, None, None, None, None, None, year_from, year_to, bool(refereed_only)) if (year_from is not None or year_to is not None or refereed_only) else None
|
|
195
|
+
q = f"{op}(bibcode:{b})" + (f" AND {extra}" if extra else "")
|
|
196
|
+
res = await self.search(q, n, s, abstract_chars=0)
|
|
197
|
+
return ok({"of": b, "relation": op, "count": len(res["docs"]), "num_found": res["num_found"], "papers": res["docs"], "provenance": self._prov(q, "search/query", res, n, s), "caution": CAUTION})
|
|
198
|
+
|
|
199
|
+
async def tool_references(self, bibcode, rows=20, sort="citation_count desc", year_from=None, year_to=None, refereed_only=False) -> dict:
|
|
200
|
+
return await self._related("references", bibcode, rows, sort, year_from, year_to, refereed_only)
|
|
201
|
+
|
|
202
|
+
async def tool_citations(self, bibcode, rows=20, sort="citation_count desc", year_from=None, year_to=None, refereed_only=False) -> dict:
|
|
203
|
+
return await self._related("citations", bibcode, rows, sort, year_from, year_to, refereed_only)
|
|
204
|
+
|
|
205
|
+
async def tool_object(self, object, year_from=None, year_to=None, refereed_only=True, rows=15, sort="citation_count desc", also_query=None) -> dict: # noqa: A002
|
|
206
|
+
if not self.configured():
|
|
207
|
+
return dict(NOT_CONFIGURED)
|
|
208
|
+
q = build_query(also_query, None, None, None, None, object, None, year_from, year_to, bool(refereed_only))
|
|
209
|
+
n, s = integer(rows, "rows", 1, 50), choice(sort, "sort", SORTS, "citation_count desc")
|
|
210
|
+
res = await self.search(q, n, s, abstract_chars=0)
|
|
211
|
+
note = ("ADS resolves object names through SIMBAD and NED, so a name ADS does not know, or that is ambiguous, can return nothing or the wrong object: check the first hits. "
|
|
212
|
+
f"Sorted by {s}; refereed only = {bool(refereed_only)}.")
|
|
213
|
+
return ok({"object": _val(object, "object", 80), "count": len(res["docs"]), "num_found": res["num_found"], "papers": res["docs"], "note": note,
|
|
214
|
+
"provenance": self._prov(q, "search/query", res, n, s), "caution": CAUTION})
|
|
215
|
+
|
|
216
|
+
async def tool_libraries(self) -> dict:
|
|
217
|
+
if not self.configured():
|
|
218
|
+
return dict(NOT_CONFIGURED)
|
|
219
|
+
body, r = await self._get("/biblib/libraries", {"rows": 100})
|
|
220
|
+
libs = [{"id": x.get("id"), "name": x.get("name"), "description": (x.get("description") or "")[:200], "num_documents": x.get("num_documents"), "public": x.get("public"),
|
|
221
|
+
"owner": x.get("owner"), "permission": x.get("permission"), "date_last_modified": x.get("date_last_modified")} for x in (body.get("libraries") or [])]
|
|
222
|
+
return ok({"count": len(libs), "libraries": libs, "provenance": provenance("NASA ADS (api.adsabs.harvard.edu/v1)", endpoint="biblib/libraries", rate_limit_remaining=r.headers.get("X-RateLimit-Remaining")),
|
|
223
|
+
"note": "These are the libraries of the ADS account that owns your token: only libraries that account owns or that were shared with it appear. Read-only."})
|
|
224
|
+
|
|
225
|
+
async def tool_library(self, library_id, rows=25, start=0) -> dict:
|
|
226
|
+
if not self.configured():
|
|
227
|
+
return dict(NOT_CONFIGURED)
|
|
228
|
+
lid = text(library_id, "library_id", 64)
|
|
229
|
+
if not LIBRARY_ID.match(lid):
|
|
230
|
+
raise ToolError("bad_input", "library_id looks like the code in an ADS library address (6-64 letters, digits, - or _); list them with ads_libraries")
|
|
231
|
+
n, st = integer(rows, "rows", 1, 50), integer(start, "start", 0, 100000)
|
|
232
|
+
body, r = await self._get(f"/biblib/libraries/{lid}", {"rows": n, "start": st})
|
|
233
|
+
bibs = [str(b) for b in (body.get("documents") or []) if BIBCODE.match(str(b))]
|
|
234
|
+
meta = body.get("metadata") or {}
|
|
235
|
+
papers: list[dict] = []
|
|
236
|
+
if bibs:
|
|
237
|
+
res = await self.search("bibcode:(" + " OR ".join(bibs) + ")", len(bibs), "date desc", abstract_chars=0)
|
|
238
|
+
by = {p["bibcode"]: p for p in res["docs"]}
|
|
239
|
+
papers = [by[b] for b in bibs if b in by]
|
|
240
|
+
return ok({"library": {"id": lid, "name": meta.get("name"), "description": (meta.get("description") or "")[:300], "num_documents": meta.get("num_documents"), "public": meta.get("public")},
|
|
241
|
+
"start": st, "count": len(papers), "papers": papers, "bibcodes_without_metadata": [b for b in bibs if b not in {p['bibcode'] for p in papers}],
|
|
242
|
+
"provenance": provenance("NASA ADS (api.adsabs.harvard.edu/v1)", endpoint="biblib/libraries/{id} + search/query", rate_limit_remaining=r.headers.get("X-RateLimit-Remaining")), "caution": CAUTION})
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""A small model-agnostic tool-calling loop: the same few lines drive any chat model that can call functions, and any place the tools live.
|
|
3
|
+
|
|
4
|
+
chat anything with `async chat(messages, tools) -> {"content": str | None, "tool_calls": [{"id", "name", "arguments": dict}]}`
|
|
5
|
+
(OpenAICompatChat: any OpenAI-compatible /chat/completions endpoint, hosted or local; ScriptedChat: a fixed plan, for offline runs and tests)
|
|
6
|
+
executor anything with `async list_tools()` and `async call(name, arguments) -> dict`
|
|
7
|
+
(LocalExecutor: the in-process Runtime; McpExecutor: any MCP server, stdio command or Streamable-HTTP URL)
|
|
8
|
+
|
|
9
|
+
`run_agent` returns a Trace: the final text, every tool call with its outcome, and how the run ended. The benchmark harness (bench.py) and the case study (examples/case_study.py) both use it.
|
|
10
|
+
No API key is read from anywhere but the environment variable you name; keys are never written to a trace.
|
|
11
|
+
"""
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
import shlex
|
|
17
|
+
from dataclasses import dataclass, field
|
|
18
|
+
from typing import Any, Protocol
|
|
19
|
+
|
|
20
|
+
import httpx
|
|
21
|
+
|
|
22
|
+
from .runtime import Runtime
|
|
23
|
+
|
|
24
|
+
MAX_TOOL_TEXT = 6000 # characters of one tool result shown to the model (the trace keeps the size and whether it was cut)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Chat(Protocol):
|
|
28
|
+
async def chat(self, messages: list[dict], tools: list[dict]) -> dict: ...
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class Executor(Protocol):
|
|
32
|
+
async def list_tools(self) -> list[dict]: ...
|
|
33
|
+
async def call(self, name: str, arguments: dict) -> dict: ...
|
|
34
|
+
async def aclose(self) -> None: ...
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
# ------------------------------------------------------------------------------------------------------------------------------ executors
|
|
38
|
+
class LocalExecutor:
|
|
39
|
+
def __init__(self, runtime: Runtime, names: list[str] | None = None):
|
|
40
|
+
self.rt, self.names = runtime, names
|
|
41
|
+
|
|
42
|
+
async def list_tools(self) -> list[dict]:
|
|
43
|
+
return [{"name": t.name, "description": t.full_description(), "input_schema": t.schema()} for t in self.rt.tools.values() if self.names is None or t.name in self.names]
|
|
44
|
+
|
|
45
|
+
async def call(self, name: str, arguments: dict) -> dict:
|
|
46
|
+
if self.names is not None and name not in self.names:
|
|
47
|
+
return {"ok": False, "error": "unknown_tool", "message": f"{name} is not one of the tools offered in this task"}
|
|
48
|
+
return await self.rt.acall(name, arguments)
|
|
49
|
+
|
|
50
|
+
async def aclose(self) -> None:
|
|
51
|
+
await self.rt.aclose()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class McpExecutor:
|
|
55
|
+
"""Tools served by any MCP server. `target` is a URL (Streamable HTTP, for example http://127.0.0.1:8765/mcp), a command line (stdio, for example 'casper-astro-tools serve'), or an MCPServer/Client-compatible object."""
|
|
56
|
+
|
|
57
|
+
def __init__(self, target: Any, names: list[str] | None = None):
|
|
58
|
+
self.target, self.names = target, names
|
|
59
|
+
self._client: Any = None
|
|
60
|
+
self._cm: Any = None
|
|
61
|
+
|
|
62
|
+
async def _open(self) -> Any:
|
|
63
|
+
if self._client is None:
|
|
64
|
+
from mcp import Client, StdioServerParameters
|
|
65
|
+
t = self.target
|
|
66
|
+
if isinstance(t, str) and not t.startswith(("http://", "https://")):
|
|
67
|
+
parts = shlex.split(t)
|
|
68
|
+
t = StdioServerParameters(command=parts[0], args=parts[1:])
|
|
69
|
+
self._cm = Client(t)
|
|
70
|
+
self._client = await self._cm.__aenter__()
|
|
71
|
+
return self._client
|
|
72
|
+
|
|
73
|
+
async def list_tools(self) -> list[dict]:
|
|
74
|
+
c = await self._open()
|
|
75
|
+
res = await c.list_tools()
|
|
76
|
+
return [{"name": t.name, "description": t.description or "", "input_schema": t.input_schema} for t in res.tools if self.names is None or t.name in self.names]
|
|
77
|
+
|
|
78
|
+
async def call(self, name: str, arguments: dict) -> dict:
|
|
79
|
+
if self.names is not None and name not in self.names:
|
|
80
|
+
return {"ok": False, "error": "unknown_tool", "message": f"{name} is not one of the tools offered in this task"}
|
|
81
|
+
c = await self._open()
|
|
82
|
+
res = await c.call_tool(name, arguments)
|
|
83
|
+
text = "".join(getattr(b, "text", "") for b in res.content)
|
|
84
|
+
try:
|
|
85
|
+
out = json.loads(text)
|
|
86
|
+
return out if isinstance(out, dict) else {"ok": not res.is_error, "result": out}
|
|
87
|
+
except ValueError:
|
|
88
|
+
return {"ok": not res.is_error, "text": text}
|
|
89
|
+
|
|
90
|
+
async def aclose(self) -> None:
|
|
91
|
+
if self._cm is not None:
|
|
92
|
+
await self._cm.__aexit__(None, None, None)
|
|
93
|
+
self._client = self._cm = None
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
# ------------------------------------------------------------------------------------------------------------------------------ chat back ends
|
|
97
|
+
class OpenAICompatChat:
|
|
98
|
+
"""Any OpenAI-compatible chat-completions endpoint with function calling (vLLM, llama.cpp server, Ollama's /v1, a hosted API). The key is read from the environment variable `api_key_env`."""
|
|
99
|
+
|
|
100
|
+
def __init__(self, base_url: str, model: str, *, api_key_env: str | None = None, temperature: float = 0.0, timeout: float = 300.0, max_tokens: int = 1500, extra: dict | None = None):
|
|
101
|
+
self.url = base_url.rstrip("/") + "/chat/completions"
|
|
102
|
+
self.model, self.temperature, self.max_tokens, self.extra = model, temperature, max_tokens, extra or {}
|
|
103
|
+
key = os.environ.get(api_key_env, "") if api_key_env else ""
|
|
104
|
+
self.headers = {"Content-Type": "application/json", **({"Authorization": f"Bearer {key}"} if key else {})}
|
|
105
|
+
self.http = httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=15.0))
|
|
106
|
+
self.usage = {"prompt_tokens": 0, "completion_tokens": 0, "calls": 0}
|
|
107
|
+
|
|
108
|
+
async def chat(self, messages: list[dict], tools: list[dict]) -> dict:
|
|
109
|
+
body = {"model": self.model, "messages": messages, "temperature": self.temperature, "max_tokens": self.max_tokens, **self.extra}
|
|
110
|
+
if tools:
|
|
111
|
+
body["tools"] = [{"type": "function", "function": {"name": t["name"], "description": t["description"], "parameters": t["input_schema"]}} for t in tools]
|
|
112
|
+
body["tool_choice"] = "auto"
|
|
113
|
+
r = await self.http.post(self.url, headers=self.headers, json=body)
|
|
114
|
+
if r.status_code != 200:
|
|
115
|
+
raise RuntimeError(f"the endpoint answered HTTP {r.status_code}: {r.text[:200]}")
|
|
116
|
+
data = r.json()
|
|
117
|
+
msg = (data.get("choices") or [{}])[0].get("message") or {}
|
|
118
|
+
u = data.get("usage") or {}
|
|
119
|
+
self.usage["prompt_tokens"] += int(u.get("prompt_tokens") or 0)
|
|
120
|
+
self.usage["completion_tokens"] += int(u.get("completion_tokens") or 0)
|
|
121
|
+
self.usage["calls"] += 1
|
|
122
|
+
calls = []
|
|
123
|
+
for i, tc in enumerate(msg.get("tool_calls") or []):
|
|
124
|
+
fn = tc.get("function") or {}
|
|
125
|
+
raw = fn.get("arguments")
|
|
126
|
+
try:
|
|
127
|
+
args = json.loads(raw) if isinstance(raw, str) and raw.strip() else (raw if isinstance(raw, dict) else {})
|
|
128
|
+
except ValueError:
|
|
129
|
+
args = {"__unparsable_arguments__": str(raw)[:200]}
|
|
130
|
+
calls.append({"id": tc.get("id") or f"call_{i}", "name": fn.get("name", ""), "arguments": args if isinstance(args, dict) else {}})
|
|
131
|
+
return {"content": msg.get("content"), "tool_calls": calls}
|
|
132
|
+
|
|
133
|
+
async def aclose(self) -> None:
|
|
134
|
+
await self.http.aclose()
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
class ScriptedChat:
|
|
138
|
+
"""A fixed plan instead of a model: first the tool calls (one assistant turn each), then the final answer. Used for the offline case study and for testing the loop."""
|
|
139
|
+
|
|
140
|
+
def __init__(self, calls: list[dict], final: str):
|
|
141
|
+
self.calls, self.final, self.i = list(calls), final, 0
|
|
142
|
+
|
|
143
|
+
async def chat(self, messages: list[dict], tools: list[dict]) -> dict:
|
|
144
|
+
if self.i < len(self.calls):
|
|
145
|
+
c = self.calls[self.i]
|
|
146
|
+
self.i += 1
|
|
147
|
+
return {"content": None, "tool_calls": [{"id": f"s{self.i}", "name": c["tool"], "arguments": c.get("arguments", {})}]}
|
|
148
|
+
return {"content": self.final, "tool_calls": []}
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
# ------------------------------------------------------------------------------------------------------------------------------ the loop
|
|
152
|
+
@dataclass
|
|
153
|
+
class Trace:
|
|
154
|
+
final_text: str = ""
|
|
155
|
+
calls: list[dict] = field(default_factory=list)
|
|
156
|
+
steps: int = 0
|
|
157
|
+
ended: str = "answered" # answered | max_steps | error
|
|
158
|
+
error: str = ""
|
|
159
|
+
messages: list[dict] = field(default_factory=list)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
SYSTEM = ("You are an astronomy assistant with tools. Use the tools for every number you report; do not compute from memory what a tool can compute. "
|
|
163
|
+
"When you have the answer, finish with one line exactly of the form `ANSWER: <value>` (a number without units unless the question asks for text).")
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
async def run_agent(chat: Chat, executor: Executor, question: str, *, system: str = SYSTEM, max_steps: int = 8, tool_names: list[str] | None = None, keep_messages: bool = False) -> Trace:
|
|
167
|
+
tools = [t for t in await executor.list_tools() if tool_names is None or t["name"] in tool_names]
|
|
168
|
+
messages: list[dict] = [{"role": "system", "content": system}, {"role": "user", "content": question}]
|
|
169
|
+
tr = Trace()
|
|
170
|
+
for step in range(1, max_steps + 1):
|
|
171
|
+
tr.steps = step
|
|
172
|
+
try:
|
|
173
|
+
reply = await chat.chat(messages, tools)
|
|
174
|
+
except Exception as exc: # noqa: BLE001 - a model or network failure ends this task, not the whole run
|
|
175
|
+
tr.ended, tr.error = "error", f"{type(exc).__name__}: {str(exc)[:200]}"
|
|
176
|
+
break
|
|
177
|
+
calls = reply.get("tool_calls") or []
|
|
178
|
+
if not calls:
|
|
179
|
+
tr.final_text = reply.get("content") or ""
|
|
180
|
+
tr.ended = "answered"
|
|
181
|
+
messages.append({"role": "assistant", "content": tr.final_text})
|
|
182
|
+
break
|
|
183
|
+
messages.append({"role": "assistant", "content": reply.get("content"), "tool_calls": [
|
|
184
|
+
{"id": c["id"], "type": "function", "function": {"name": c["name"], "arguments": json.dumps(c["arguments"])}} for c in calls]})
|
|
185
|
+
for c in calls:
|
|
186
|
+
res = await executor.call(c["name"], c["arguments"])
|
|
187
|
+
body = json.dumps(res, default=str, ensure_ascii=False)
|
|
188
|
+
cut = len(body) > MAX_TOOL_TEXT
|
|
189
|
+
tr.calls.append({"name": c["name"], "arguments": c["arguments"], "ok": bool(res.get("ok")), "error": None if res.get("ok") else res.get("error"), "result_chars": len(body), "result_cut": cut, "result": res})
|
|
190
|
+
messages.append({"role": "tool", "tool_call_id": c["id"], "content": body[:MAX_TOOL_TEXT] + (" ...[cut]" if cut else "")})
|
|
191
|
+
else:
|
|
192
|
+
tr.ended = "max_steps"
|
|
193
|
+
if keep_messages:
|
|
194
|
+
tr.messages = messages
|
|
195
|
+
return tr
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""The Python API.
|
|
3
|
+
|
|
4
|
+
>>> import casper_astro_tools as at
|
|
5
|
+
>>> at.call("astro_convert_coordinates", lon="18h36m56.3364s", lat="+38:47:01.291", to_frame="galactic")["output"]["l_deg"]
|
|
6
|
+
67.4482...
|
|
7
|
+
>>> at.list_tools()[0]["name"]
|
|
8
|
+
|
|
9
|
+
`call` is synchronous (it must not be used inside a running event loop: use `await acall(...)` there). Every call returns a dict: {"ok": true, ...} or {"ok": false, "error": code, "message": ...}.
|
|
10
|
+
"""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import asyncio
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from .runtime import Runtime
|
|
17
|
+
|
|
18
|
+
_default: Runtime | None = None
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def runtime(**kw: Any) -> Runtime:
|
|
22
|
+
"""The shared default runtime (created on first use). Pass keyword arguments of Runtime only on the first call, or use Runtime(...) yourself."""
|
|
23
|
+
global _default
|
|
24
|
+
if _default is None:
|
|
25
|
+
_default = Runtime(**kw)
|
|
26
|
+
return _default
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def reset() -> None:
|
|
30
|
+
global _default
|
|
31
|
+
_default = None
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
async def acall(name: str, **arguments: Any) -> dict:
|
|
35
|
+
return await runtime().acall(name, arguments)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def call(name: str, **arguments: Any) -> dict:
|
|
39
|
+
return call_sync(name, arguments)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def call_sync(name: str, arguments: dict | None = None) -> dict:
|
|
43
|
+
return asyncio.run(_run(name, arguments or {}))
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
async def _run(name: str, arguments: dict) -> dict:
|
|
47
|
+
# a fresh event loop per call needs fresh HTTP clients: build a throw-away runtime configured like the default one
|
|
48
|
+
rt = runtime()
|
|
49
|
+
fresh = Runtime(groups=rt.groups, network=rt.network) if not rt.offline else rt
|
|
50
|
+
try:
|
|
51
|
+
return await fresh.acall(name, arguments)
|
|
52
|
+
finally:
|
|
53
|
+
if fresh is not rt:
|
|
54
|
+
await fresh.aclose()
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def list_tools(group: str | None = None) -> list[dict]:
|
|
58
|
+
return [t.listing() for t in runtime().tools.values() if group in (None, t.group)]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def tool_names() -> list[str]:
|
|
62
|
+
return list(runtime().tools)
|