astronereus 0.2.1__tar.gz

astronereus-0.2.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/

astronereus-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Vines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

astronereus-0.2.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: astronereus
+Version: 0.2.1
+Summary: Python frontend for Nereus.jl — Nested-Evidence Recovery of Exoplanets by Unified Sampling
+Project-URL: Homepage, https://github.com/jvines/Nereus.jl
+Project-URL: Repository, https://github.com/jvines/nereus-py
+Project-URL: Issues, https://github.com/jvines/nereus-py/issues
+Author-email: Jose Vines <jose.vines.l@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astrometry,bayesian,exoplanets,gaia,mcmc,nested-sampling,radial-velocity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Requires-Dist: zstandard>=0.22; python_version < '3.14'
+Provides-Extra: test
+Requires-Dist: numpy>=1.24; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Provides-Extra: zstd
+Requires-Dist: zstandard>=0.22; extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# astronereus
+
+Python frontend for [Nereus](https://github.com/jvines/Nereus.jl) — trans-dimensional
+Bayesian inference for exoplanet orbits.
+
+**You do not need Julia.** Nereus itself is Julia, but this package fetches a
+prebuilt runtime on first use and runs it out-of-process in a warm daemon.
+Nothing is compiled at install time.
+
+```sh
+pip install astronereus
+python -c "import astronereus; astronereus.install()"
+```
+
+The distribution and the import are both `astronereus`. The name `nereus` on
+PyPI belongs to an unrelated geophysics package, and a distribution whose import
+name differs from its install name is a thing every user has to be told, so they
+are deliberately the same string here.
+
+## Use
+
+```python
+import astronereus
+
+summary = astronereus.run_job(cfg)          # one-shot
+
+with astronereus.session() as s:            # or reuse one warm daemon
+    a  = s.run_job(cfg_a)
+    pg = s.detect.rv_periodogram(t=t, rv=rv, rv_err=err)
+```
+
+Typed entry points per observable — `fit_rv`, `fit_transit`, `fit_astrometry`,
+`fit_rm`, `fit_tomography`, `fit_ttv`, `fit_binary`, `fit_joint` — take channel
+objects (`RV`, `Transit`, `Astrometry`, `RM`, `Night`, `TTV`, `SB2`) and return
+a `JobResult`.
+
+The first `install()` unpacks the runtime and warms it once (a few minutes);
+every process after that starts in about twenty seconds. `NEREUS_BUNDLE_URL`
+points the installer at a local file or `file://` URL — that is the intended
+path for a workshop room, where thirty people pulling half a gigabyte over
+conference wifi is not a plan.
+
+## Runtime bundles
+
+Prebuilt runtimes are attached to the
+[Nereus.jl releases](https://github.com/jvines/Nereus.jl/releases), with
+`SHA256SUMS` alongside:
+
+| platform | size |
+|---|---|
+| `macos-arm64` | 465 MiB |
+| `linux-x86_64` | 688 MiB |
+
+`install()` picks the one for your platform and verifies it against the
+published checksum. For a classroom, fetch it once and point everyone at the
+local copy instead:
+
+```sh
+export NEREUS_BUNDLE_URL=/Volumes/NEREUS/nereus-runtime-1.11.9-macos-arm64.tar.zst
+```
+
+`NEREUS_HOME` relocates the runtime cache out of the default platform cache
+directory.
+
+## Licence
+
+MIT — see `LICENSE`.

astronereus-0.2.1/README.md

@@ -0,0 +1,67 @@
+# astronereus
+
+Python frontend for [Nereus](https://github.com/jvines/Nereus.jl) — trans-dimensional
+Bayesian inference for exoplanet orbits.
+
+**You do not need Julia.** Nereus itself is Julia, but this package fetches a
+prebuilt runtime on first use and runs it out-of-process in a warm daemon.
+Nothing is compiled at install time.
+
+```sh
+pip install astronereus
+python -c "import astronereus; astronereus.install()"
+```
+
+The distribution and the import are both `astronereus`. The name `nereus` on
+PyPI belongs to an unrelated geophysics package, and a distribution whose import
+name differs from its install name is a thing every user has to be told, so they
+are deliberately the same string here.
+
+## Use
+
+```python
+import astronereus
+
+summary = astronereus.run_job(cfg)          # one-shot
+
+with astronereus.session() as s:            # or reuse one warm daemon
+    a  = s.run_job(cfg_a)
+    pg = s.detect.rv_periodogram(t=t, rv=rv, rv_err=err)
+```
+
+Typed entry points per observable — `fit_rv`, `fit_transit`, `fit_astrometry`,
+`fit_rm`, `fit_tomography`, `fit_ttv`, `fit_binary`, `fit_joint` — take channel
+objects (`RV`, `Transit`, `Astrometry`, `RM`, `Night`, `TTV`, `SB2`) and return
+a `JobResult`.
+
+The first `install()` unpacks the runtime and warms it once (a few minutes);
+every process after that starts in about twenty seconds. `NEREUS_BUNDLE_URL`
+points the installer at a local file or `file://` URL — that is the intended
+path for a workshop room, where thirty people pulling half a gigabyte over
+conference wifi is not a plan.
+
+## Runtime bundles
+
+Prebuilt runtimes are attached to the
+[Nereus.jl releases](https://github.com/jvines/Nereus.jl/releases), with
+`SHA256SUMS` alongside:
+
+| platform | size |
+|---|---|
+| `macos-arm64` | 465 MiB |
+| `linux-x86_64` | 688 MiB |
+
+`install()` picks the one for your platform and verifies it against the
+published checksum. For a classroom, fetch it once and point everyone at the
+local copy instead:
+
+```sh
+export NEREUS_BUNDLE_URL=/Volumes/NEREUS/nereus-runtime-1.11.9-macos-arm64.tar.zst
+```
+
+`NEREUS_HOME` relocates the runtime cache out of the default platform cache
+directory.
+
+## Licence
+
+MIT — see `LICENSE`.

astronereus-0.2.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+# Hatchling >=1.28 emits Metadata-Version 2.5, which twine 6.2 rejects as
+# invalid and which older installers do not understand. 2.4 is the newest
+# version the whole toolchain agrees on.
+requires = ["hatchling<1.28"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astronereus"
+version = "0.2.1"
+description = "Python frontend for Nereus.jl — Nested-Evidence Recovery of Exoplanets by Unified Sampling"
+requires-python = ">=3.10"
+dependencies = ["zstandard>=0.22; python_version < '3.14'"]
+license = "MIT"
+readme = "README.md"
+authors = [{name = "Jose Vines", email = "jose.vines.l@gmail.com"}]
+keywords = ["exoplanets", "radial-velocity", "astrometry", "gaia", "mcmc",
+            "nested-sampling", "bayesian"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Astronomy",
+  "Programming Language :: Python :: 3",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+]
+
+[project.urls]
+Homepage = "https://github.com/jvines/Nereus.jl"
+Repository = "https://github.com/jvines/nereus-py"
+Issues = "https://github.com/jvines/nereus-py/issues"
+
+[project.optional-dependencies]
+zstd = ["zstandard>=0.22"]
+test = ["pytest>=7", "numpy>=1.24"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astronereus"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/astronereus/julia/daemon.jl" = "astronereus/julia/daemon.jl"
+
+[tool.hatch.build.targets.sdist]
+# Explicit allow-list. The sdist once shipped DEPLOYMENT.md -- internal
+# topology and fleet hostnames -- and a PyPI upload cannot be undone. That
+# file now lives outside the repo entirely, but the allow-list stays: it is
+# the cheaper guarantee.
+include = ["src", "tools", "README.md", "LICENSE", "pyproject.toml"]

astronereus-0.2.1/src/astronereus/__init__.py

@@ -0,0 +1,42 @@
+"""Nereus — Nested-Evidence Recovery of Exoplanets by Unified Sampling.
+
+Python frontend. Julia runs out-of-process in a warm daemon; you never need
+Julia installed and nothing is compiled at install time.
+
+    import astronereus
+    astronereus.install(url=...)              # once: fetch the runtime bundle
+
+    summary = nereus.run_job(cfg)        # one-shot
+
+    with astronereus.session() as s:          # or reuse one warm daemon
+        a = s.run_job(cfg_a)
+        pg = s.detect.rv_periodogram(t=t, rv=rv, rv_err=err)
+"""
+from ._runtime import (JULIA_VERSION, CPU_TARGETS, BundleError, install,
+                       find_julia, julia_home,
+                       is_installed, platform_tag, runtime_dir, cache_root,
+                       julia_env)
+from ._daemon import JuliaDaemon, DaemonError
+from ._api import Session, session, run_job, ping
+from ._fit import (fit_rv, fit_transit, fit_astrometry, fit_rm,
+                   fit_tomography, fit_ttv, fit_binary, fit_joint)
+from .channels import RV, Transit, Astrometry, RM, Night, TTV, SB2
+from .stopping import Stopping
+from . import engines, channels
+from ._result import JobResult, JobFailed, Figures
+
+__all__ = ["JULIA_VERSION", "CPU_TARGETS", "BundleError", "DaemonError",
+           "JuliaDaemon", "Session", "install", "is_installed", "platform_tag",
+           "runtime_dir", "cache_root", "julia_env", "find_julia", "julia_home",
+           "daemon", "session", "run_job", "ping",
+           "JobResult", "JobFailed", "Figures",
+           "fit_rv", "fit_transit", "fit_astrometry", "fit_rm",
+           "fit_tomography", "fit_ttv", "fit_binary", "fit_joint",
+           "RV", "Transit", "Astrometry", "RM", "Night", "TTV", "SB2",
+           "Stopping", "engines", "channels"]
+__version__ = "0.2.1"
+
+
+def daemon(**kw) -> JuliaDaemon:
+    """A warm Julia daemon. Use as a context manager."""
+    return JuliaDaemon(**kw)

astronereus-0.2.1/src/astronereus/_api.py

@@ -0,0 +1,181 @@
+"""The user-facing API.
+
+`JuliaDaemon.call("run_job", cfg)` is transport plumbing and should never
+appear in user code: it is stringly-typed, gives no completion, no signature,
+no docstring, and any typo becomes a runtime error from Julia. This module is
+the typed facade over it.
+
+Three levels, in increasing order of control:
+
+    import astronereus
+    summary = nereus.run_job(cfg)                  # 1. just do the thing
+
+    with astronereus.session() as s:                    # 2. reuse one warm daemon
+        a = s.run_job(cfg_a)
+        b = s.run_job(cfg_b)
+        pg = s.detect.rv_periodogram(t, rv, err)
+
+    with astronereus.session() as s:                    # 3. escape hatch
+        s.raw("some.new.action", payload)
+
+Level 1 lazily starts a process-wide daemon on first use and reuses it, so the
+~20 s `using Nereus` is paid once per interpreter, not per call.
+"""
+
+from __future__ import annotations
+
+import atexit
+import threading
+from typing import Any, Sequence
+
+from ._daemon import JuliaDaemon
+from ._result import JobResult, JobFailed
+from . import _features as _F
+
+_shared: "Session | None" = None
+_shared_lock = threading.Lock()
+
+
+class _Namespace:
+    """Groups related actions, e.g. ``s.detect.transits`` -> "detection.transits"."""
+
+    def __init__(self, session: "Session", prefix: str, actions: dict[str, str]):
+        self._s, self._prefix, self._actions = session, prefix, actions
+
+    def __dir__(self):
+        return sorted(self._actions)
+
+    def __getattr__(self, name: str):
+        if name not in self._actions:
+            raise AttributeError(
+                f"{self._prefix}.{name} is not a Nereus action. "
+                f"Available: {', '.join(sorted(self._actions))}")
+        action = self._actions[name]
+
+        def _call(**payload):
+            return self._s.raw(action, payload)
+
+        _call.__name__ = name
+        _call.__doc__ = f"Nereus compute action {action!r}."
+        return _call
+
+
+
+class Session:
+    """A warm Julia session. Use as a context manager."""
+
+    def __init__(self, **daemon_kw):
+        self._daemon = JuliaDaemon(**daemon_kw)
+        g = lambda: self
+        self.detect = _F._Group(g, "detect", _F.DETECT)
+        self.detrend = _F._Group(g, "detrend", _F.DETREND)
+        self.tomogram = _F._Group(g, "tomogram", _F.TOMOGRAM)
+        self.diagnostics = _F._Group(g, "diagnostics", _F.DIAGNOSTICS)
+
+    # -- lifecycle ---------------------------------------------------------
+    def start(self) -> "Session":
+        self._daemon.start()
+        return self
+
+    def close(self) -> None:
+        self._daemon.stop()
+
+    def __enter__(self) -> "Session":
+        return self.start()
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- the actual API ----------------------------------------------------
+    def run_job(self, config: dict[str, Any] | str, *,
+                check: bool = True,
+                timeout: float | None = None) -> JobResult:
+        """Run a full Nereus job and return its summary.
+
+        `config` is a JOB_CONFIG dict (or a path to one). Nereus writes
+        `summary.json`, `chains.nc` and the plot tree into `config["output_dir"]`
+        and returns the summary, which includes a `figures` manifest mapping
+        logical names to paths.
+        """
+        # Validate client-side: a missing output_dir otherwise surfaces as an
+        # opaque Julia error several minutes into a run.
+        if isinstance(config, dict) and not config.get("output_dir"):
+            raise ValueError("job config needs an 'output_dir' — Nereus writes "
+                             "summary.json, chains.nc and the plot tree there")
+        res = JobResult(self.raw("run_job", config, timeout=timeout))
+        return res.check() if check else res
+
+    def ping(self) -> dict[str, Any]:
+        """Liveness + which Julia/CPU/thread count the daemon actually has."""
+        return self.raw("ping", {})
+
+    def raw(self, action: str, payload: Any = None, *,
+            timeout: float | None = None) -> Any:
+        """Escape hatch: call an action by name.
+
+        Only for actions newer than this client. If you find yourself using it
+        routinely, the action belongs in the typed API above.
+        """
+        return self._daemon.call(action, payload, timeout=timeout)
+
+    @property
+    def log_path(self):
+        """Where the daemon's stdout/stderr goes — read this when a job dies."""
+        return self._daemon.log_path
+
+
+def session(**daemon_kw) -> Session:
+    """A new warm Julia session (not the process-wide shared one)."""
+    return Session(**daemon_kw)
+
+
+def _shared_session(**kw) -> Session:
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = Session(**kw).start()
+            atexit.register(_shared.close)
+    return _shared
+
+
+def run_job(config: dict[str, Any] | str, *, check: bool = True,
+            timeout: float | None = None, **session_kw) -> JobResult:
+    """Run a job on a lazily-started, process-wide daemon.
+
+    Convenience for one-shot use. Prefer `with astronereus.session() as s:` when
+    making several calls, so the lifetime is explicit.
+    """
+    return _shared_session(**session_kw).run_job(config, check=check, timeout=timeout)
+
+
+def ping(**session_kw) -> dict[str, Any]:
+    return _shared_session(**session_kw).ping()
+
+
+# --- per-technique entry points, bound to a session -------------------------
+def _bind(name):
+    from . import _fit
+    fn = getattr(_fit, name)
+    def method(self, *a, **kw):
+        kw.setdefault("session", self)
+        return fn(*a, **kw)
+    method.__name__ = name
+    method.__doc__ = fn.__doc__
+    return method
+
+
+for _n in ("fit_rv", "fit_transit", "fit_astrometry", "fit_rm",
+           "fit_tomography", "fit_ttv", "fit_binary", "fit_joint"):
+    setattr(Session, _n, _bind(_n))
+
+# post-hoc operations that act on a finished run
+for _n, _act in (("evidence", "evidence"),
+                 ("detection_limits", "detection_limits"),
+                 ("select_planets", "select_planets"),
+                 ("select_noise", "select_noise"),
+                 ("pre_white", "pre_white")):
+    def _mk(action):
+        def m(self, **payload):
+            return self.raw(action, payload)
+        return m
+    setattr(Session, _n, _mk(_act))

astronereus-0.2.1/src/astronereus/_daemon.py

@@ -0,0 +1,197 @@
+"""Supervise a warm Julia daemon and talk to it over a unix socket.
+
+Deliberately NOT juliacall: embedding deadlocks under Julia's `@threads`, which
+every sampler uses. A separate process also means a crashing job cannot take the
+Python interpreter with it.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import socket
+import struct
+import subprocess
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+from . import _runtime
+
+_HDR = struct.Struct(">Q")
+
+
+def _enc(o):
+    """JSON fallback for the types a scientific payload actually carries.
+
+    Channels are built with `dataclasses.asdict`, which leaves numpy arrays
+    untouched, so every realistic call ships ndarrays. Non-finite floats pass
+    through as NaN/Infinity — `daemon.jl` reads with `allow_inf = true`.
+    """
+    if hasattr(o, "tolist"):            # ndarray, numpy scalar
+        return o.tolist()
+    if hasattr(o, "item"):              # any remaining 0-d numpy scalar
+        return o.item()
+    if isinstance(o, (set, frozenset)):
+        return sorted(o)
+    raise TypeError(f"cannot send {type(o).__name__} to Julia")
+
+
+class DaemonError(RuntimeError):
+    pass
+
+
+class JuliaDaemon:
+    def __init__(self, version: str = _runtime.JULIA_VERSION,
+                 project: str | os.PathLike | None = None,
+                 threads: str | int = "auto",
+                 preload: str | None = "Nereus",
+                 api_file: str | list[str] | None = None,
+                 startup_timeout: float = 300.0,
+                 idle_timeout: float = 1800.0):
+        self.version = version
+        self.project = str(project) if project else None
+        self.threads = threads
+        self.preload = preload
+        # Extra Julia file to include after `using` — the public API surface.
+        # In the shipped package this lives inside Nereus itself; during
+        # bring-up it is loaded from a path so it can be iterated on.
+        self.api_file = api_file
+        self.startup_timeout = startup_timeout
+        # The daemon exits on its own if we die abnormally (atexit cannot run
+        # on SIGKILL/OOM) or if nothing talks to it for this long. Verified:
+        # without this a -9'd parent leaves a ~530 MB Julia process behind.
+        self.idle_timeout = idle_timeout
+        self._proc: subprocess.Popen | None = None
+        self._sock: socket.socket | None = None
+        self._lock = threading.Lock()
+        self._tmp = Path(tempfile.mkdtemp(prefix="nereus-daemon-"))
+        self.sock_path = self._tmp / "daemon.sock"
+        self.log_path = self._tmp / "daemon.log"
+
+    # -- lifecycle ---------------------------------------------------------
+    def start(self) -> "JuliaDaemon":
+        if self._proc is not None:
+            return self
+        julia, env = _runtime.julia_env(self.version)
+        entry = Path(__file__).parent / "julia" / "daemon.jl"
+
+        cmd = [str(julia), f"-t{self.threads}", "--startup-file=no"]
+        if self.project:
+            cmd.append(f"--project={self.project}")
+        # Preload inside the daemon so the ~20 s `using` cost is paid once, at
+        # boot, rather than on the first job.
+        ppid = os.getpid()
+        if self.preload:
+            _files = ([self.api_file] if isinstance(self.api_file, str)
+                      else list(self.api_file or []))
+            api_inc = "".join(f'include("{p}"); ' for p in _files)
+            cmd += ["-e", f"@eval using {self.preload}; "
+                          f"{api_inc}"
+                          f"include(\"{entry}\"); "
+                          f"serve(ARGS[1]; parent_pid=parse(Int,ARGS[2]), "
+                          f"idle=parse(Float64,ARGS[3]))",
+                    str(self.sock_path), str(ppid), str(self.idle_timeout)]
+        else:
+            cmd += [str(entry), str(self.sock_path), str(ppid),
+                    str(self.idle_timeout)]
+
+        log = self.log_path.open("wb")
+        self._proc = subprocess.Popen(cmd, env=env, stdout=log, stderr=log)
+        atexit.register(self.stop)
+
+        deadline = time.time() + self.startup_timeout
+        while time.time() < deadline:
+            if self._proc.poll() is not None:
+                raise DaemonError(
+                    f"daemon exited with {self._proc.returncode}\n"
+                    f"--- log ---\n{self.log_path.read_text(errors='replace')[-4000:]}")
+            if self.sock_path.exists():
+                try:
+                    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                    s.connect(str(self.sock_path))
+                    self._sock = s
+                    return self
+                except OSError:
+                    pass
+            time.sleep(0.1)
+        self.stop()
+        raise DaemonError(
+            f"daemon did not become ready within {self.startup_timeout}s\n"
+            f"--- log ---\n{self.log_path.read_text(errors='replace')[-4000:]}")
+
+    def stop(self) -> None:
+        if self._sock is not None:
+            try:
+                self._send({"action": "shutdown"})
+            except Exception:
+                pass
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._sock = None
+        if self._proc is not None:
+            try:
+                self._proc.wait(timeout=10)
+            except Exception:
+                self._proc.kill()
+            self._proc = None
+
+    # -- transport ---------------------------------------------------------
+    def _send(self, obj) -> None:
+        body = json.dumps(obj, default=_enc).encode()
+        self._sock.sendall(_HDR.pack(len(body)) + body)
+
+    def _recvn(self, n: int) -> bytes:
+        buf = bytearray()
+        while len(buf) < n:
+            chunk = self._sock.recv(n - len(buf))
+            if not chunk:
+                raise DaemonError("daemon closed the connection")
+            buf += chunk
+        return bytes(buf)
+
+    def call(self, action: str, payload=None, timeout: float | None = None):
+        with self._lock:
+            # start() INSIDE the lock: two threads that both saw _sock is None
+            # would otherwise each spawn a Julia process.
+            if self._sock is None:
+                self.start()
+            try:
+                self._sock.settimeout(timeout)
+                self._send({"action": action, "payload": payload or {}})
+                (n,) = _HDR.unpack(self._recvn(8))
+                resp = json.loads(self._recvn(n))
+            except Exception:
+                # Framing is length-prefixed, so a half-read response leaves
+                # the stream desynchronised — the next call would read the
+                # tail of this one as an 8-byte header. There is no
+                # resynchronisation point, so drop the connection; the next
+                # call reconnects.
+                #
+                # NOTE: a timeout here does NOT stop the Julia job. It keeps
+                # running in the daemon. Call stop() if you need it dead.
+                self._drop()
+                raise
+        if not resp.get("ok"):
+            raise DaemonError(resp.get("error", "unknown error") + "\n"
+                              + resp.get("backtrace", ""))
+        return resp.get("result")
+
+    def _drop(self) -> None:
+        """Close the socket and forget it, so the next call reconnects."""
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._sock = None
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, *exc):
+        self.stop()