psrmcp 0.1.0__py3-none-any.whl

psrmcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server wrapping pulsar astronomy software (dspsr, psrchive, tempo2, psrcat, PINT)."""
+
+__version__ = "0.1.0"
+
+SERVER_NAME = "psrmcp"

psrmcp/_context.py

@@ -0,0 +1,44 @@
+"""AppContext assembly: wire execution kernel pieces together (server.py helper)."""
+
+from __future__ import annotations
+
+import sys
+
+from .adapters.base import BackendManager
+from .config import Config
+from .execution.jobs import JobManager
+from .execution.runner import ProcessRunner
+from .execution.tasks import TasksCapability
+from .execution.workspace import ArtifactStore, Workspace
+from .paths import PathResolver
+from .tools._common import AppContext
+
+
+def build_context(cfg: Config) -> AppContext:
+    ws = Workspace(cfg.server.workspace.expanduser())
+    runner = ProcessRunner(
+        default_timeout_s=60.0,
+        max_threads=cfg.limits.max_threads,
+        max_output_bytes=int(cfg.limits.max_input_gb * (1 << 30)),
+        audit_log=ws.logs_dir / "audit.jsonl",
+    )
+    store = ArtifactStore(ws, max_output_bytes=int(cfg.limits.max_output_gb * (1 << 30)))
+    jobs = JobManager(
+        ws.sessions / "jobs.sqlite3",
+        max_concurrent=cfg.server.max_concurrent_jobs,
+        job_timeout_s=cfg.server.job_timeout_s,
+    )
+    resolver = PathResolver(cfg, artifact_lookup=store.lookup_id)
+    backends = BackendManager(cfg, runner, python_exe=sys.executable)
+    return AppContext(
+        cfg=cfg,
+        runner=runner,
+        ws=ws,
+        store=store,
+        jobs=jobs,
+        resolver=resolver,
+        backends=backends,
+        tasks=TasksCapability(),
+        python_exe=sys.executable,
+        audit_log=ws.logs_dir / "audit.jsonl",
+    )

psrmcp/adapters/base.py

@@ -0,0 +1,185 @@
+"""Backend probing and binary resolution (adapters layer, DESIGN.md §3)."""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..config import Config
+from ..errors import PsrmcpError, env_missing
+from ..execution.runner import ProcessRunner
+from ..models.common import BackendInfo
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class BackendSpec:
+    """How to locate and version-check one backend."""
+
+    name: str
+    # Ordered candidate binaries: (path-or-name, version_args, version_regex)
+    probes: tuple[tuple[str, tuple[str, ...], str], ...] = ()
+    capabilities: tuple[str, ...] = ()
+    python: bool = False  # python-package backend (PINT), probed via interpreter import
+
+
+DSPSR_SPEC = BackendSpec(
+    name="dspsr",
+    probes=(("dspsr", ("--version",), r"([0-9]+\.[0-9]+[.\-][^\s]*|DSPSR v?[0-9][^\s]*)"),),
+    capabilities=("dedisperse",),
+)
+
+PSRCHIVE_SPEC = BackendSpec(
+    name="psrchive",
+    probes=(
+        # 实测:psrstat/psradd/psrconv 的 --version 打印 "PSRCHIVE <日期> <commit>";
+        # psrchive_config 只 dump 配置无版本,vap/pat 不认 --version。
+        ("psrstat", ("--version",), r"(PSRCHIVE\s+\S+\s+\S+|[0-9]+\.[^\s]+)"),
+        ("psrchive-config", ("--version",), r"([0-9]+\.[^\s]+)"),
+    ),
+    capabilities=("inspect", "convert", "merge", "zap", "profile", "toa"),
+)
+
+TEMPO2_SPEC = BackendSpec(
+    name="tempo2",
+    probes=(("tempo2", ("-v",), r"(tempo2[^\s]*|[0-9]{4}[^\s]*)"),),
+    capabilities=("timing_fit", "timing_diagnose"),
+)
+
+PSRCAT_SPEC = BackendSpec(
+    name="psrcat",
+    probes=(("psrcat", ("-v",), r"([0-9]{4}[^\s]*|[0-9]+\.[^\s]+)"),),
+    capabilities=("catalog_search", "catalog_get", "ephemeris_export"),
+)
+
+PINT_SPEC = BackendSpec(name="pint", python=True, capabilities=("timing_fit", "timing_diagnose", "ephemeris_export"))
+
+ALL_SPECS: dict[str, BackendSpec] = {
+    s.name: s for s in (DSPSR_SPEC, PSRCHIVE_SPEC, TEMPO2_SPEC, PSRCAT_SPEC, PINT_SPEC)
+}
+
+
+class BackendManager:
+    """Resolves binaries from config paths or PATH, probes versions, caches results."""
+
+    def __init__(self, cfg: Config, runner: ProcessRunner, *, python_exe: str | None = None) -> None:
+        self._cfg = cfg
+        self._runner = runner
+        self._python_exe = python_exe or "python3"
+        self._cache: dict[str, BackendInfo] = {}
+
+    def configured_path(self, name: str) -> str | None:
+        b = self._cfg.backends
+        return {
+            "dspsr": b.dspsr,
+            "psrchive": b.psrchive_bin,
+            "tempo2": b.tempo2,
+            "psrcat": b.psrcat,
+        }.get(name)
+
+    def resolve(self, binary: str) -> str | None:
+        """Resolve a binary name to an executable path, or None."""
+        if "/" in binary:
+            return binary if Path(binary).exists() else None
+        configured = self.configured_path(binary)
+        if configured:
+            if Path(configured).is_file():
+                return str(configured)
+            found = shutil.which(configured)
+            if found:
+                return found
+        return shutil.which(binary)
+
+    def resolve_psrchive_tool(self, tool: str) -> str | None:
+        """Resolve a psrchive suite binary (vap, psrstat, ...)."""
+        base = self._cfg.backends.psrchive_bin
+        if base:
+            candidate = Path(base) / tool
+            if candidate.is_file():
+                return str(candidate)
+        return shutil.which(tool)
+
+    async def probe_all(self, *, refresh: bool = False) -> dict[str, BackendInfo]:
+        if refresh:
+            self._cache.clear()
+        for name, spec in ALL_SPECS.items():
+            if name not in self._cache:
+                self._cache[name] = await self._probe(spec)
+        return dict(self._cache)
+
+    async def get(self, name: str, *, refresh: bool = False) -> BackendInfo:
+        if refresh or name not in self._cache:
+            self._cache[name] = await self._probe(ALL_SPECS[name])
+        return self._cache[name]
+
+    def cached(self, name: str) -> BackendInfo | None:
+        return self._cache.get(name)
+
+    async def require(self, name: str) -> BackendInfo:
+        info = await self.get(name)
+        if not info.available:
+            reason = info.reason or "不可用"
+            raise env_missing(name, reason)
+        return info
+
+    async def _probe(self, spec: BackendSpec) -> BackendInfo:
+        if spec.python:
+            return await self._probe_python(spec)
+        for binary, args, regex in spec.probes:
+            path = self.resolve_psrchive_tool(binary) if spec.name == "psrchive" else self.resolve(binary)
+            if path is None:
+                continue
+            info = await self._probe_binary(spec, path, list(args), regex)
+            if info.available:
+                return info
+        reasons = {
+            "dspsr": "未在 PATH 或配置路径中找到 dspsr",
+            "psrchive": "未找到 psrchive 工具链(psrstat/psrchive-config)",
+            "tempo2": "未找到 tempo2,或 tempo2 未启用",
+            "psrcat": "未找到 psrcat 二进制",
+        }
+        unavailable_reason = reasons.get(spec.name, f"未找到 {spec.name}")
+        if spec.name == "tempo2" and not self._cfg.backends.tempo2_enabled:
+            unavailable_reason = "配置中 tempo2_enabled=false"
+        return BackendInfo(available=False, reason=unavailable_reason, capabilities=list(spec.capabilities))
+
+    async def _probe_binary(self, spec: BackendSpec, path: str, args: list[str], regex: str) -> BackendInfo:
+        try:
+            result = await self._runner.run([path, *args], timeout_s=20.0)
+        except PsrmcpError as exc:
+            return BackendInfo(available=False, path=path, reason=str(exc.message))
+        text = (result.stdout_text + result.stderr_text).strip()
+        if result.exit_code != 0 and not text:
+            return BackendInfo(
+                available=False, path=path, reason=f"版本查询退出码 {result.exit_code}"
+            )
+        m = re.search(regex, text)
+        version = m.group(1) if m else text.splitlines()[0][:80] if text else None
+        return BackendInfo(available=True, path=path, version=version, capabilities=list(spec.capabilities))
+
+    async def _probe_python(self, spec: BackendSpec) -> BackendInfo:
+        if spec.name == "pint" and not self._cfg.backends.pint_enabled:
+            return BackendInfo(available=False, reason="配置中 pint_enabled=false")
+        try:
+            result = await self._runner.run(
+                [
+                    self._python_exe,
+                    "-c",
+                    "import importlib;m=importlib.import_module('%s');print(getattr(m,'__version__','?'))"
+                    % ("pint" if spec.name == "pint" else spec.name),
+                ],
+                timeout_s=60.0,
+            )
+        except PsrmcpError as exc:
+            return BackendInfo(available=False, reason=exc.message)
+        version = result.stdout_text.strip() or None
+        if result.exit_code != 0 or version is None:
+            return BackendInfo(
+                available=False,
+                reason=f"python 包 {spec.name} 导入失败: {result.stderr_tail(400)}",
+            )
+        return BackendInfo(available=True, version=version, capabilities=list(spec.capabilities))

psrmcp/adapters/dspsr.py

@@ -0,0 +1,50 @@
+"""dspsr adapter: dedisperse/fold command builder.
+
+dspsr applies coherent dedispersion automatically to raw voltage backends when a
+DM is available; filterbank inputs are incoherently dedispersed. The MCP `mode`
+parameter is therefore advisory: it is validated, recorded in provenance, and a
+warning is emitted when it cannot be honoured. TODO(contract) marks flags to
+verify on the installed version.
+"""
+
+from __future__ import annotations
+
+
+
+def dedisperse_cmd(
+    binary: str,
+    source: str,
+    *,
+    dm: float | None = None,
+    nbin: int | None = None,
+    nchan: int | None = None,
+    nsubint: int | None = None,
+    out_prefix: str = "out",
+    out_ext: str = "ar",
+    threads: int | None = None,
+    ephemeris: str | None = None,
+) -> list[str]:
+    args = [binary]
+    if dm is not None:
+        args += ["-D", f"{dm:.12g}"]
+    if ephemeris is not None:
+        # -E: 用 par 生成相位预测器(输入头内嵌 predictor 缺失时必需,
+        # 如 filterbank/无 POLYCO 的 PSRFITS)
+        args += ["-E", str(ephemeris)]
+    if nbin is not None:
+        args += ["-b", str(nbin)]
+    if nchan is not None:
+        # TODO(contract): "-F" configures output channels (e.g. -F 512:D).
+        args += ["-F", str(nchan)]
+    if nsubint is not None:
+        # TODO(contract): "-L" sets sub-integration length in seconds; deriving
+        # it from nsubint requires the observation duration, so pass through as
+        # a best-effort "-L" only when the caller computed it.
+        args += ["-L", str(nsubint)]
+    if threads is not None:
+        args += ["-t", str(threads)]  # TODO(contract): thread flag spelling.
+    # -O 是输出文件名前缀(不是目录):产物 = <prefix>.<out_ext>
+    args += ["-O", out_prefix]
+    args += ["-e", out_ext]
+    args.append(source)
+    return args

psrmcp/adapters/pint.py

@@ -0,0 +1,58 @@
+"""Bridge to the PINT worker subprocess (JSON over stdin/stdout, one request)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ..errors import ErrorCode, PsrmcpError
+from ..execution.runner import ProcessRunner
+
+_WORKER_MODULE = "psrmcp.workers.pint_worker"
+
+
+def worker_argv(python_exe: str | None = None) -> list[str]:
+    return [python_exe or sys.executable, "-m", _WORKER_MODULE]
+
+
+async def call_worker(
+    runner: ProcessRunner,
+    request: dict[str, Any],
+    *,
+    cwd: Path,
+    python_exe: str | None = None,
+    timeout_s: float = 600.0,
+) -> dict[str, Any]:
+    """Run one worker request; returns the parsed response dict."""
+    argv = worker_argv(python_exe)
+    result = await runner.run(
+        argv,
+        cwd=cwd,
+        stdin_bytes=json.dumps(request).encode("utf-8"),
+        timeout_s=timeout_s,
+    )
+    return parse_worker_output(result.stdout_text)
+
+
+def parse_worker_output(text: str) -> dict[str, Any]:
+    lines = [ln for ln in text.strip().splitlines() if ln.strip()]
+    if not lines:
+        raise PsrmcpError(ErrorCode.PROCESS_FAILED, "PINT worker 没有输出")
+    try:
+        resp = json.loads(lines[-1])
+    except json.JSONDecodeError as exc:
+        raise PsrmcpError(
+            ErrorCode.PROCESS_FAILED,
+            f"PINT worker 输出不是 JSON: {exc}",
+            details={"stdout_tail": text[-2000:]},
+        ) from exc
+    if not resp.get("ok", False):
+        code_raw = str(resp.get("code", "E_PROCESS_FAILED"))
+        try:
+            code = ErrorCode(code_raw)
+        except ValueError:
+            code = ErrorCode.PROCESS_FAILED
+        raise PsrmcpError(code, str(resp.get("message", "PINT worker failed")))
+    return resp

psrmcp/adapters/psrcat.py

@@ -0,0 +1,197 @@
+"""psrcat adapter: query builders, row parser and ephemeris export.
+
+Verified against psrcat 2.6.1 (real install, 2026-10-24): name selection is
+positional (no -name flag); column keywords are raj/decj (ra/dec unknown);
+`-o short` rows carry a leading row-number token; there is no -db flag (the
+catalogue is located via the PSRCAT_FILE environment variable), no -binary
+flag and no cone-search flags — cone and binary filtering happen in Python
+(tools/catalog.py) because -boundary mishandles negative DEC.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..errors import invalid_input
+
+# psrcat -c columns -> record fields (TOOLS.md section 2 CatalogRecord).
+# raj/decj are the accepted keywords; ver/assoc(tel) do not exist. assoc is the
+# catalogue association string and is surfaced under the observatory field
+# (closest contract slot; ATNF exposes no per-row observatory).
+# `binary` 列是真正的 BINARY 模型(T2/DD/...;孤立脉冲星为 "*");
+# `bincomp` 是伴星成分描述符(如 "He[vbv+08]"),不能当模型名用。
+PSRCAT_COLUMNS: list[str] = "name raj decj p0 f0 p1 dm binary assoc".split()
+
+PSRCAT_FIELD: dict[str, str] = dict(
+    kv.split(":", 1)
+    for kv in (
+        "name:name raj:ra_str decj:dec_str p0:p0_s f0:f0_hz p1:p1 dm:dm "
+        "binary:binary_model assoc:observatory"
+    ).split()
+)
+
+
+def psrcat_base(binary: str) -> list[str]:
+    # No -db flag exists: psrcat locates the catalogue via $PSRCAT_FILE
+    # (callers set it in the subprocess environment).
+    return [binary, "-nohead", "-o", "short"]
+
+
+def catalog_get_cmd(binary: str, name: str, db_path: str | None = None) -> list[str]:
+    # Name selection is positional; -name is not a psrcat flag.
+    return psrcat_base(binary) + [name, "-c", " ".join(PSRCAT_COLUMNS)]
+
+
+def catalog_search_cmd(
+    binary: str,
+    *,
+    conditions: list[str],
+    columns: list[str] | None = None,
+) -> list[str]:
+    # Cone and binary-only filtering are done in Python (no CLI flags; the
+    # -boundary alternative fails on negative DEC).
+    args = psrcat_base(binary)
+    if conditions:
+        args += ["-l", " && ".join(conditions)]
+    args += ["-c", " ".join(columns or PSRCAT_COLUMNS)]
+    return args
+
+
+def psrcat_ephem_cmd(binary: str, name: str) -> list[str]:
+    """`psrcat -e`: complete TEMPO-format ephemeris (BINARY/PB/ECC/CLK/EPHEM...)."""
+    return [binary, name, "-e"]
+
+
+def parse_psrcat_row(text: str) -> dict[str, Any]:
+    """Parse one whitespace-separated psrcat data row into a record dict."""
+    tokens = text.split()
+    # -o short prepends a per-row line-number token even with -nohead.
+    if tokens and tokens[0].isdigit():
+        tokens = tokens[1:]
+    if len(tokens) < len(PSRCAT_COLUMNS):
+        raise ValueError(f"psrcat row has {len(tokens)} columns, expected {len(PSRCAT_COLUMNS)}")
+    # assoc(tel) may contain no spaces in -o short mode; if it does, the row is
+    # longer: associate tokens greedily from the right (ver is last).
+    if len(tokens) > len(PSRCAT_COLUMNS):
+        extra = len(tokens) - len(PSRCAT_COLUMNS)
+        observatory = " ".join(tokens[8 : 9 + extra])
+        tokens = tokens[:8] + [observatory] + tokens[9 + extra :]
+    record: dict[str, Any] = {}
+    for col, raw in zip(PSRCAT_COLUMNS, tokens):
+        field = PSRCAT_FIELD.get(col, col)
+        record[field] = _num(raw)
+    return record
+
+
+_PSRCAT_NA = {"*", "-", "INVALID"}
+
+
+def _num(raw: str) -> Any:
+    if raw.strip() in _PSRCAT_NA:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        return raw
+
+
+# ---------------------------------------------------------------------------
+# Ephemeris export. 完整星历直接用 `psrcat -e`(实测含 BINARY/PB/ECC/
+# CLK/EPHEM,PINT/tempo2 可直接加载);build_par_text 只服务无本地星表
+# (psrqpy 在线)或带位置 override 的合成回退路径。
+# ---------------------------------------------------------------------------
+
+RA_HOURS_RE = re.compile(r"^(\d+):(\d+)(?::([\d.]+))?$")  # h:m[:s] —— 星表里两种都出现
+
+
+def hms_to_deg(hms: str) -> float:
+    m = RA_HOURS_RE.match(hms.strip())
+    if not m:
+        raise invalid_input(f"无法解析 RA: {hms!r}")
+    h, mi = float(m.group(1)), float(m.group(2))
+    sec = float(m.group(3)) if m.group(3) else 0.0
+    return (h + mi / 60 + sec / 3600) * 15.0
+
+
+def hms_to_deg_or_num(hms: str) -> float:
+    try:
+        return float(hms)
+    except ValueError:
+        return hms_to_deg(hms)
+
+
+DMS_RE = re.compile(r"^([+-]?\d+):(\d+(?:\.\d+)?)(?::([\d.]+))?$")  # d:m[.frac][:s]
+
+
+def dms_to_deg(dms: str) -> float:
+    """Parse sign d:m[:s] (psrcat emits two- or three-part DEC); numeric passthrough."""
+    m = DMS_RE.match(dms.strip())
+    if not m:
+        try:
+            return float(dms)
+        except ValueError as exc:
+            raise invalid_input(f"无法解析 DEC: {dms!r}") from exc
+    sign = -1.0 if m.group(1).startswith("-") else 1.0
+    d = abs(float(m.group(1)))
+    mi = float(m.group(2))
+    sec = float(m.group(3)) if m.group(3) else 0.0
+    return sign * (d + mi / 60 + sec / 3600)
+
+
+def build_par_text(
+    *,
+    name: str,
+    ra_deg: float | None,
+    dec_deg: float | None,
+    p0_s: float,
+    dm: float,
+    f0_hz: float | None = None,
+    p1: float | None = None,
+    peepoch_mjd: float | None = None,
+    posepoch_mjd: float | None = None,
+    binary_model: str | None = None,
+    tempo2: bool = False,
+) -> str:
+    lines = [f"PSRJ            {name}"]
+    if ra_deg is not None:
+        lines.append(f"RAJ             {_deg_to_hms(ra_deg)}")
+    if dec_deg is not None:
+        lines.append(f"DECJ            {_deg_to_dms(dec_deg)}")
+    lines.append(f"P0              {p0_s!r}")
+    if f0_hz is not None:
+        lines.append(f"F0              {f0_hz!r}")
+    if p1 is not None:
+        lines.append(f"P1              {p1!r}")
+    lines.append(f"DM              {dm!r}")
+    lines.append("PEPOCH          " + (f"{peepoch_mjd!r}" if peepoch_mjd is not None else "50000.0"))
+    lines.append("POSEPOCH        " + (f"{posepoch_mjd!r}" if posepoch_mjd is not None else "50000.0"))
+    if binary_model:
+        lines.append(f"BINARY          {binary_model}")
+    lines.append("CLK             " + ("TT(TAI)" if tempo2 else "UTC(NIST)"))
+    lines.append("UNITS           " + ("TDB" if tempo2 else "TCB"))
+    lines.append("TIMEEPH         " + ("T2 Barycentric" if tempo2 else "FB90"))
+    return "\n".join(lines) + "\n"
+
+
+def _deg_to_hms(deg: float) -> str:
+    hours = deg / 15.0
+    h = int(hours)
+    m_full = (hours - h) * 60
+    mi = int(m_full)
+    s = (m_full - mi) * 60
+    return f"{h:02d}:{mi:02d}:{s:07.4f}"
+
+
+def _deg_to_dms(deg: float) -> str:
+    sign = "-" if deg < 0 else "+"
+    a = abs(deg)
+    d = int(a)
+    m_full = (a - d) * 60
+    mi = int(m_full)
+    s = (m_full - mi) * 60
+    return f"{sign}{d:02d}:{mi:02d}:{s:07.4f}"