juniper-recurrence-client 0.1.0__tar.gz

juniper_recurrence_client-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: juniper-recurrence-client
+Version: 0.1.0
+Summary: HTTP client for the juniper-recurrence service (the Δt-native LMU recurrence model + cross-validation API)
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Repository, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Issues, https://github.com/pcalnon/juniper-recurrence/issues
+Keywords: juniper,recurrence,lmu,http-client,rest,time-series,cross-validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: responses>=0.23; extra == "test"
+Provides-Extra: observability
+Requires-Dist: juniper-observability>=0.3.1; extra == "observability"
+
+# juniper-recurrence-client
+
+HTTP client for the **juniper-recurrence** service — the FastAPI app wrapping the Δt-native LMU
+recurrence model and its cross-validation API. A lean `requests`-based client mirroring
+[`juniper-data-client`](https://github.com/pcalnon/juniper-data-client) and
+[`juniper-cascor-client`](https://github.com/pcalnon/juniper-cascor-client), so consumers
+(notably **juniper-canopy**'s recurrence backend adapter) drive every Juniper backend the same way.
+
+## Install
+
+```bash
+pip install juniper-recurrence-client          # once published
+pip install -e ".[test]"                        # local development
+```
+
+`requests`-only at the core; `pip install juniper-recurrence-client[observability]` adds the
+optional `juniper-observability` integration (X-Request-ID propagation + the `on_request` hook).
+
+## Quick start
+
+```python
+from juniper_recurrence_client import JuniperRecurrenceClient
+
+client = JuniperRecurrenceClient("http://localhost:8211", api_key="…")
+
+# Train the LMU regressor on a dataset (by id / name / generator)
+client.train(name="equities", d=16)
+
+# Predict — inline X with Δt, or a dataset reference
+client.predict(dataset_id="ds-1")
+
+# Walk-forward cross-validation over the dataset's _full split
+result = client.crossval(name="equities", n_folds=4, scheme="expanding", embargo=2)
+print(result["eval_aggregate"])
+
+# Inspect
+client.get_model()        # topology + metrics
+client.training_status()  # state + events
+client.is_ready()         # readiness probe
+```
+
+## API surface
+
+| Method | Endpoint |
+|--------|----------|
+| `train(*, dataset_id / name / generator, params, split, d, theta, ridge)` | `POST /v1/train` |
+| `training_status()` | `GET /v1/training/status` |
+| `predict(*, X / dt / target_dt / seq_lengths, or a dataset ref)` | `POST /v1/predict` |
+| `crossval(*, n_folds, scheme, embargo, min_train, dataset ref, d, theta, ridge)` | `POST /v1/crossval` |
+| `crossval_status()` | `GET /v1/crossval/status` |
+| `get_model()` | `GET /v1/model` |
+| `get_dataset()` | `GET /v1/dataset` |
+| `health_check()` / `is_ready()` / `wait_for_ready()` | `GET /v1/health[/ready]` |
+
+## Authentication
+
+Pass `api_key=…`, or set `JUNIPER_RECURRENCE_API_KEY` (or the Docker-secret
+`JUNIPER_RECURRENCE_API_KEY_FILE`, a path whose stripped contents are the key). The key is sent
+as the `X-API-Key` header. Note the asymmetry: the **server** reads the *plural*
+`JUNIPER_RECURRENCE_API_KEYS` (its accepted set); the **client** sends one key under the
+*singular* env var.
+
+## Errors
+
+All errors derive from `JuniperRecurrenceClientError`: `JuniperRecurrenceConnectionError`,
+`JuniperRecurrenceTimeoutError`, `JuniperRecurrenceNotFoundError` (404),
+`JuniperRecurrenceConflictError` (409 — a run already in progress, or no trained model yet),
+`JuniperRecurrenceValidationError` (400/422), `JuniperRecurrenceConfigurationError`.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pcalnon/juniper-recurrence/blob/main/LICENSE).

juniper_recurrence_client-0.1.0/README.md

@@ -0,0 +1,72 @@
+# juniper-recurrence-client
+
+HTTP client for the **juniper-recurrence** service — the FastAPI app wrapping the Δt-native LMU
+recurrence model and its cross-validation API. A lean `requests`-based client mirroring
+[`juniper-data-client`](https://github.com/pcalnon/juniper-data-client) and
+[`juniper-cascor-client`](https://github.com/pcalnon/juniper-cascor-client), so consumers
+(notably **juniper-canopy**'s recurrence backend adapter) drive every Juniper backend the same way.
+
+## Install
+
+```bash
+pip install juniper-recurrence-client          # once published
+pip install -e ".[test]"                        # local development
+```
+
+`requests`-only at the core; `pip install juniper-recurrence-client[observability]` adds the
+optional `juniper-observability` integration (X-Request-ID propagation + the `on_request` hook).
+
+## Quick start
+
+```python
+from juniper_recurrence_client import JuniperRecurrenceClient
+
+client = JuniperRecurrenceClient("http://localhost:8211", api_key="…")
+
+# Train the LMU regressor on a dataset (by id / name / generator)
+client.train(name="equities", d=16)
+
+# Predict — inline X with Δt, or a dataset reference
+client.predict(dataset_id="ds-1")
+
+# Walk-forward cross-validation over the dataset's _full split
+result = client.crossval(name="equities", n_folds=4, scheme="expanding", embargo=2)
+print(result["eval_aggregate"])
+
+# Inspect
+client.get_model()        # topology + metrics
+client.training_status()  # state + events
+client.is_ready()         # readiness probe
+```
+
+## API surface
+
+| Method | Endpoint |
+|--------|----------|
+| `train(*, dataset_id / name / generator, params, split, d, theta, ridge)` | `POST /v1/train` |
+| `training_status()` | `GET /v1/training/status` |
+| `predict(*, X / dt / target_dt / seq_lengths, or a dataset ref)` | `POST /v1/predict` |
+| `crossval(*, n_folds, scheme, embargo, min_train, dataset ref, d, theta, ridge)` | `POST /v1/crossval` |
+| `crossval_status()` | `GET /v1/crossval/status` |
+| `get_model()` | `GET /v1/model` |
+| `get_dataset()` | `GET /v1/dataset` |
+| `health_check()` / `is_ready()` / `wait_for_ready()` | `GET /v1/health[/ready]` |
+
+## Authentication
+
+Pass `api_key=…`, or set `JUNIPER_RECURRENCE_API_KEY` (or the Docker-secret
+`JUNIPER_RECURRENCE_API_KEY_FILE`, a path whose stripped contents are the key). The key is sent
+as the `X-API-Key` header. Note the asymmetry: the **server** reads the *plural*
+`JUNIPER_RECURRENCE_API_KEYS` (its accepted set); the **client** sends one key under the
+*singular* env var.
+
+## Errors
+
+All errors derive from `JuniperRecurrenceClientError`: `JuniperRecurrenceConnectionError`,
+`JuniperRecurrenceTimeoutError`, `JuniperRecurrenceNotFoundError` (404),
+`JuniperRecurrenceConflictError` (409 — a run already in progress, or no trained model yet),
+`JuniperRecurrenceValidationError` (400/422), `JuniperRecurrenceConfigurationError`.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pcalnon/juniper-recurrence/blob/main/LICENSE).

juniper_recurrence_client-0.1.0/juniper_recurrence_client/__init__.py

@@ -0,0 +1,34 @@
+"""juniper-recurrence-client — HTTP client for the juniper-recurrence service.
+
+A lean ``requests``-based client wrapping the juniper-recurrence FastAPI app's REST surface
+(train / predict / cross-validate / inspect / health). Mirrors juniper-data-client and
+juniper-cascor-client so consumers (notably juniper-canopy's recurrence backend adapter) drive
+every Juniper backend the same way.
+"""
+
+from __future__ import annotations
+
+from juniper_recurrence_client._version import __version__
+from juniper_recurrence_client.client import JuniperRecurrenceClient, RequestHook
+from juniper_recurrence_client.exceptions import (
+    JuniperRecurrenceClientError,
+    JuniperRecurrenceConfigurationError,
+    JuniperRecurrenceConflictError,
+    JuniperRecurrenceConnectionError,
+    JuniperRecurrenceNotFoundError,
+    JuniperRecurrenceTimeoutError,
+    JuniperRecurrenceValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "JuniperRecurrenceClient",
+    "RequestHook",
+    "JuniperRecurrenceClientError",
+    "JuniperRecurrenceConnectionError",
+    "JuniperRecurrenceTimeoutError",
+    "JuniperRecurrenceNotFoundError",
+    "JuniperRecurrenceConflictError",
+    "JuniperRecurrenceValidationError",
+    "JuniperRecurrenceConfigurationError",
+]

juniper_recurrence_client-0.1.0/juniper_recurrence_client/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the juniper-recurrence-client version.
+
+Kept import-free so setuptools can parse ``__version__`` statically at build time
+(``[tool.setuptools.dynamic]`` in pyproject.toml) without importing requests.
+"""
+
+__version__ = "0.1.0"

juniper_recurrence_client-0.1.0/juniper_recurrence_client/client.py

@@ -0,0 +1,433 @@
+"""REST API client for the juniper-recurrence service.
+
+A lean ``requests``-based client wrapping the juniper-recurrence FastAPI app's REST surface
+(train / predict / cross-validate / inspect / health), for consumers such as juniper-canopy's
+recurrence backend adapter. Mirrors juniper-data-client's transport machinery: an idempotent-only
+retry policy, ``X-API-Key`` auth with ``_FILE`` Docker-secret indirection, typed exceptions, the
+optional ``on_request`` instrumentation hook, and best-effort ``X-Request-ID`` propagation.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional
+from urllib.parse import urlparse
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from juniper_recurrence_client.constants import (
+    API_KEY_ENV_VAR,
+    API_KEY_FILE_ENV_VAR,
+    API_KEY_HEADER_NAME,
+    API_VERSION_PATH_SUFFIX,
+    DEFAULT_BACKOFF_FACTOR,
+    DEFAULT_BASE_URL,
+    DEFAULT_READY_POLL_INTERVAL,
+    DEFAULT_READY_TIMEOUT,
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUT,
+    DEFAULT_URL_SCHEME_PREFIX,
+    ENDPOINT_CROSSVAL,
+    ENDPOINT_CROSSVAL_STATUS,
+    ENDPOINT_DATASET,
+    ENDPOINT_HEALTH,
+    ENDPOINT_HEALTH_READY,
+    ENDPOINT_MODEL,
+    ENDPOINT_PREDICT,
+    ENDPOINT_TRAIN,
+    ENDPOINT_TRAINING_STATUS,
+    HEALTH_READY_STATUS,
+    HTTP_400_BAD_REQUEST,
+    HTTP_404_NOT_FOUND,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_POOL_CONNECTIONS,
+    HTTP_POOL_MAXSIZE,
+    RETRY_ALLOWED_METHODS,
+    RETRYABLE_STATUS_CODES,
+    URL_SCHEME_PREFIXES,
+)
+from juniper_recurrence_client.exceptions import (
+    JuniperRecurrenceClientError,
+    JuniperRecurrenceConflictError,
+    JuniperRecurrenceConnectionError,
+    JuniperRecurrenceNotFoundError,
+    JuniperRecurrenceTimeoutError,
+    JuniperRecurrenceValidationError,
+)
+
+logger = logging.getLogger("juniper_recurrence_client.client")
+
+
+def _resolve_api_key_from_env() -> Optional[str]:
+    """Resolve the juniper-recurrence API key from the environment.
+
+    Honors the Docker-secret ``JUNIPER_RECURRENCE_API_KEY_FILE`` indirection (a file whose
+    stripped contents are the key) before the plain ``JUNIPER_RECURRENCE_API_KEY`` env var, so a
+    consumer that mounts the key as a file and leaves ``api_key`` unset still authenticates.
+    """
+    file_path = os.environ.get(API_KEY_FILE_ENV_VAR)
+    if file_path:
+        try:
+            content = Path(file_path).read_text(encoding="utf-8").strip()
+        except OSError:
+            content = ""
+        if content:
+            return content
+    return os.environ.get(API_KEY_ENV_VAR)
+
+
+#: Optional instrumentation hook, invoked once per HTTP call with
+#: ``(method, url, status, duration_ms, error)``. ``error is None`` is the canonical success
+#: signal (``status`` may be set even on the typed-error paths). Mirrors juniper-data-client so
+#: canopy/cascor can pass the same Prometheus/structured-log closure they already use.
+RequestHook = Callable[[str, str, Optional[int], float, Optional[BaseException]], None]
+
+
+def _noop_request_hook(
+    method: str,
+    url: str,
+    status: Optional[int],
+    duration_ms: float,
+    error: Optional[BaseException],
+) -> None:
+    """Default :data:`RequestHook` — does nothing (named so the default is a real callable)."""
+
+
+def _dataset_ref(
+    *,
+    dataset_id: Optional[str],
+    name: Optional[str],
+    generator: Optional[str],
+    params: Optional[dict[str, Any]],
+    split: str,
+) -> dict[str, Any]:
+    """Build the app's ``DatasetRef`` body from selection kwargs.
+
+    Exactly one of ``dataset_id`` / ``name`` / ``generator`` is expected; the server validates
+    that invariant and returns 422 otherwise.
+    """
+    ref: dict[str, Any] = {"split": split}
+    if dataset_id is not None:
+        ref["dataset_id"] = dataset_id
+    if name is not None:
+        ref["name"] = name
+    if generator is not None:
+        ref["generator"] = generator
+    if params is not None:
+        ref["params"] = params
+    return ref
+
+
+class JuniperRecurrenceClient:
+    """Client for the juniper-recurrence REST API (train / predict / cross-validate / inspect).
+
+    Automatic retry (idempotent methods only), connection pooling, and ``X-API-Key`` auth.
+
+    Example:
+        >>> client = JuniperRecurrenceClient("http://localhost:8211")
+        >>> client.train(name="equities", d=16)
+        >>> preds = client.predict(dataset_id="ds-1")
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
+        api_key: Optional[str] = None,
+        on_request: Optional[RequestHook] = None,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            base_url: Base URL of the juniper-recurrence app (default ``http://localhost:8211``).
+            timeout: Per-request timeout in seconds.
+            retries: Retry attempts for transient failures on idempotent methods.
+            backoff_factor: Exponential backoff factor for retries.
+            api_key: API key for ``X-API-Key`` auth. If unset, resolved from
+                ``JUNIPER_RECURRENCE_API_KEY`` (and its ``_FILE`` form).
+            on_request: Optional instrumentation hook (see :data:`RequestHook`); defaults to a
+                no-op. Hook exceptions are caught and logged so instrumentation never crashes a
+                request path.
+        """
+        self.base_url = self._normalize_url(base_url)
+        self.timeout = timeout
+        self.retries = retries
+        self.backoff_factor = backoff_factor
+        self.session = self._create_session()
+        self._on_request: RequestHook = on_request or _noop_request_hook
+
+        resolved_api_key = api_key or _resolve_api_key_from_env()
+        if resolved_api_key:
+            self.session.headers[API_KEY_HEADER_NAME] = resolved_api_key
+
+    def _normalize_url(self, url: str) -> str:
+        """Normalize the base URL: ensure a scheme, drop a trailing slash and any ``/v1`` suffix."""
+        url = url.strip()
+        if not url.startswith(URL_SCHEME_PREFIXES):
+            url = f"{DEFAULT_URL_SCHEME_PREFIX}{url}"
+        parsed = urlparse(url)
+        normalized = f"{parsed.scheme}://{parsed.netloc}{parsed.path}".rstrip("/")
+        if normalized.endswith(API_VERSION_PATH_SUFFIX):
+            normalized = normalized[: -len(API_VERSION_PATH_SUFFIX)]
+        return normalized
+
+    def _create_session(self) -> requests.Session:
+        """Create a ``requests.Session`` with the idempotent-only retry policy + pooling."""
+        session = requests.Session()
+        retry_strategy = Retry(
+            total=self.retries,
+            backoff_factor=self.backoff_factor,
+            status_forcelist=RETRYABLE_STATUS_CODES,
+            allowed_methods=RETRY_ALLOWED_METHODS,
+        )
+        adapter = HTTPAdapter(
+            max_retries=retry_strategy,
+            pool_connections=HTTP_POOL_CONNECTIONS,
+            pool_maxsize=HTTP_POOL_MAXSIZE,
+        )
+        for scheme in URL_SCHEME_PREFIXES:
+            session.mount(scheme, adapter)
+        return session
+
+    def _request(self, method: str, endpoint: str, **kwargs: Any) -> requests.Response:  # noqa: C901
+        """Make an HTTP request, mapping transport/HTTP errors to typed exceptions.
+
+        Raises:
+            JuniperRecurrenceConnectionError / JuniperRecurrenceTimeoutError: transport failures.
+            JuniperRecurrenceNotFoundError (404), JuniperRecurrenceConflictError (409),
+            JuniperRecurrenceValidationError (400/422), or JuniperRecurrenceClientError (other).
+        """
+        url = f"{self.base_url}{endpoint}"
+        kwargs.setdefault("timeout", self.timeout)
+
+        # Best-effort X-Request-ID propagation via juniper-observability (no-op if absent or
+        # unset); a caller-supplied X-Request-ID always wins.
+        headers = dict(kwargs.get("headers") or {})
+        if "X-Request-ID" not in headers:
+            try:
+                from juniper_observability import request_id_var  # noqa: PLC0415
+
+                rid = request_id_var.get()
+                if rid:
+                    headers["X-Request-ID"] = rid
+                    kwargs["headers"] = headers
+            except (ImportError, LookupError):
+                pass
+
+        start = time.monotonic()
+        response: Optional[requests.Response] = None
+        outgoing_error: Optional[BaseException] = None
+        try:
+            try:
+                response = self.session.request(method, url, **kwargs)
+            except requests.exceptions.ConnectionError as e:
+                outgoing_error = JuniperRecurrenceConnectionError(f"Failed to connect to juniper-recurrence at {self.base_url}: {e}")
+                raise outgoing_error from e
+            except requests.exceptions.Timeout as e:
+                outgoing_error = JuniperRecurrenceTimeoutError(f"Request to {url} timed out after {self.timeout}s: {e}")
+                raise outgoing_error from e
+            except requests.exceptions.RequestException as e:
+                outgoing_error = JuniperRecurrenceClientError(f"Request failed: {e}")
+                raise outgoing_error from e
+
+            if response.ok:
+                return response
+
+            error_detail = response.text
+            try:
+                error_json = response.json()
+                if "detail" in error_json:
+                    error_detail = error_json["detail"]
+            except (ValueError, KeyError):
+                error_detail = response.text
+
+            if response.status_code == HTTP_404_NOT_FOUND:
+                outgoing_error = JuniperRecurrenceNotFoundError(f"Resource not found: {error_detail}")
+                raise outgoing_error
+            elif response.status_code == HTTP_409_CONFLICT:
+                outgoing_error = JuniperRecurrenceConflictError(f"Conflict: {error_detail}")
+                raise outgoing_error
+            elif response.status_code in (HTTP_400_BAD_REQUEST, HTTP_422_UNPROCESSABLE_ENTITY):
+                outgoing_error = JuniperRecurrenceValidationError(f"Validation error: {error_detail}")
+                raise outgoing_error
+            else:
+                outgoing_error = JuniperRecurrenceClientError(f"Request failed ({response.status_code}): {error_detail}")
+                raise outgoing_error
+        finally:
+            duration_ms = (time.monotonic() - start) * 1000.0
+            status = response.status_code if response is not None else None
+            try:
+                self._on_request(method, url, status, duration_ms, outgoing_error)
+            except Exception:  # noqa: BLE001 — instrumentation must not crash production paths
+                logger.warning("on_request hook raised; suppressed to keep request path resilient", exc_info=True)
+
+    @staticmethod
+    def _parse_json(response: requests.Response) -> Any:
+        """Parse a response body as JSON, surfacing a typed error on a malformed body."""
+        try:
+            return response.json()
+        except ValueError as e:
+            preview = (response.text or "")[:200]
+            raise JuniperRecurrenceClientError(f"Malformed JSON response from {response.url}: {e}: {preview!r}") from e
+
+    # ─── Training ─────────────────────────────────────────────────────────────
+
+    def train(
+        self,
+        *,
+        dataset_id: Optional[str] = None,
+        name: Optional[str] = None,
+        generator: Optional[str] = None,
+        params: Optional[dict[str, Any]] = None,
+        split: str = "train",
+        d: Optional[int] = None,
+        theta: Optional[float] = None,
+        ridge: Optional[float] = None,
+    ) -> dict[str, Any]:
+        """``POST /v1/train`` — synchronously fit the LMU regressor on a dataset split.
+
+        Supply exactly one of ``dataset_id`` / ``name`` / ``generator``. Returns the
+        ``TrainResponse`` (``final_metrics``, ``n_epochs``, ``stopped_reason``, ``dataset``).
+        Raises :class:`JuniperRecurrenceConflictError` (409) if a run is already in progress.
+        """
+        body: dict[str, Any] = {"dataset": _dataset_ref(dataset_id=dataset_id, name=name, generator=generator, params=params, split=split)}
+        if d is not None:
+            body["d"] = d
+        if theta is not None:
+            body["theta"] = theta
+        if ridge is not None:
+            body["ridge"] = ridge
+        return self._parse_json(self._request("POST", ENDPOINT_TRAIN, json=body))
+
+    def training_status(self) -> dict[str, Any]:
+        """``GET /v1/training/status`` — current training state, metrics, and emitted events."""
+        return self._parse_json(self._request("GET", ENDPOINT_TRAINING_STATUS))
+
+    # ─── Prediction ───────────────────────────────────────────────────────────
+
+    def predict(
+        self,
+        *,
+        X: Optional[Any] = None,
+        dt: Optional[Any] = None,
+        target_dt: Optional[Any] = None,
+        seq_lengths: Optional[Any] = None,
+        dataset_id: Optional[str] = None,
+        name: Optional[str] = None,
+        generator: Optional[str] = None,
+        params: Optional[dict[str, Any]] = None,
+        split: str = "train",
+    ) -> dict[str, Any]:
+        """``POST /v1/predict`` — predictions from the trained model.
+
+        Supply exactly one of inline ``X`` (optionally with ``dt`` / ``target_dt`` /
+        ``seq_lengths``) or a dataset reference. Returns ``{"predictions": ..., "shape": ...}``.
+        """
+        body: dict[str, Any] = {}
+        if X is not None:
+            body["X"] = X
+            if dt is not None:
+                body["dt"] = dt
+            if target_dt is not None:
+                body["target_dt"] = target_dt
+            if seq_lengths is not None:
+                body["seq_lengths"] = seq_lengths
+        if dataset_id is not None or name is not None or generator is not None:
+            body["dataset"] = _dataset_ref(dataset_id=dataset_id, name=name, generator=generator, params=params, split=split)
+        return self._parse_json(self._request("POST", ENDPOINT_PREDICT, json=body))
+
+    # ─── Cross-validation ──────────────────────────────────────────────────────
+
+    def crossval(
+        self,
+        *,
+        n_folds: int,
+        dataset_id: Optional[str] = None,
+        name: Optional[str] = None,
+        generator: Optional[str] = None,
+        params: Optional[dict[str, Any]] = None,
+        split: str = "train",
+        scheme: str = "expanding",
+        embargo: int = 0,
+        min_train: Optional[int] = None,
+        d: Optional[int] = None,
+        theta: Optional[float] = None,
+        ridge: Optional[float] = None,
+    ) -> dict[str, Any]:
+        """``POST /v1/crossval`` — synchronous walk-forward cross-validation over the ``_full`` split.
+
+        Returns the ``CrossValResponse`` (per-fold ``folds`` + ``eval_aggregate`` / ``eval_std``).
+        ``scheme`` is ``"expanding"`` or ``"rolling"``. Raises 409 if a CV run is already running.
+        """
+        body: dict[str, Any] = {
+            "dataset": _dataset_ref(dataset_id=dataset_id, name=name, generator=generator, params=params, split=split),
+            "n_folds": n_folds,
+            "scheme": scheme,
+            "embargo": embargo,
+        }
+        if min_train is not None:
+            body["min_train"] = min_train
+        if d is not None:
+            body["d"] = d
+        if theta is not None:
+            body["theta"] = theta
+        if ridge is not None:
+            body["ridge"] = ridge
+        return self._parse_json(self._request("POST", ENDPOINT_CROSSVAL, json=body))
+
+    def crossval_status(self) -> dict[str, Any]:
+        """``GET /v1/crossval/status`` — the most recent cross-validation result, if any."""
+        return self._parse_json(self._request("GET", ENDPOINT_CROSSVAL_STATUS))
+
+    # ─── Inspection ────────────────────────────────────────────────────────────
+
+    def get_model(self) -> dict[str, Any]:
+        """``GET /v1/model`` — the trained model's topology + metrics (409 if none trained)."""
+        return self._parse_json(self._request("GET", ENDPOINT_MODEL))
+
+    def get_dataset(self) -> dict[str, Any]:
+        """``GET /v1/dataset`` — descriptor of the split the model was trained on (409 if none)."""
+        return self._parse_json(self._request("GET", ENDPOINT_DATASET))
+
+    # ─── Health / Readiness ────────────────────────────────────────────────────
+
+    def health_check(self) -> dict[str, Any]:
+        """``GET /v1/health`` — liveness."""
+        return self._parse_json(self._request("GET", ENDPOINT_HEALTH))
+
+    def is_ready(self) -> bool:
+        """``GET /v1/health/ready`` — ``True`` iff the service reports ready."""
+        try:
+            payload = self._parse_json(self._request("GET", ENDPOINT_HEALTH_READY))
+        except JuniperRecurrenceClientError:
+            return False
+        return payload.get("status") == HEALTH_READY_STATUS
+
+    def wait_for_ready(self, timeout: float = DEFAULT_READY_TIMEOUT, poll_interval: float = DEFAULT_READY_POLL_INTERVAL) -> bool:
+        """Poll ``/v1/health/ready`` until ready or ``timeout`` seconds elapse."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self.is_ready():
+                return True
+            time.sleep(poll_interval)
+        return self.is_ready()
+
+    # ─── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self.session.close()
+
+    def __enter__(self) -> "JuniperRecurrenceClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

juniper_recurrence_client-0.1.0/juniper_recurrence_client/constants.py

@@ -0,0 +1,97 @@
+"""Protocol-level constants for the juniper-recurrence REST client.
+
+Centralizes the literals used by ``client.py`` — base URL, endpoint paths, header names,
+HTTP/retry configuration — mirroring juniper-data-client's constants module so the wire
+contract is discoverable in one place.
+"""
+
+from typing import List, Tuple
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_RETRIES",
+    "DEFAULT_BACKOFF_FACTOR",
+    "RETRYABLE_STATUS_CODES",
+    "RETRY_ALLOWED_METHODS",
+    "HTTP_POOL_CONNECTIONS",
+    "HTTP_POOL_MAXSIZE",
+    "URL_SCHEME_PREFIXES",
+    "DEFAULT_URL_SCHEME_PREFIX",
+    "API_VERSION_PATH_SUFFIX",
+    "DEFAULT_READY_TIMEOUT",
+    "DEFAULT_READY_POLL_INTERVAL",
+    "HEALTH_READY_STATUS",
+    "API_KEY_HEADER_NAME",
+    "API_KEY_ENV_VAR",
+    "API_KEY_FILE_ENV_VAR",
+    "ENDPOINT_HEALTH",
+    "ENDPOINT_HEALTH_READY",
+    "ENDPOINT_TRAIN",
+    "ENDPOINT_TRAINING_STATUS",
+    "ENDPOINT_PREDICT",
+    "ENDPOINT_MODEL",
+    "ENDPOINT_DATASET",
+    "ENDPOINT_CROSSVAL",
+    "ENDPOINT_CROSSVAL_STATUS",
+]
+
+# ─── Service Configuration ───────────────────────────────────────────────────
+
+# The juniper-recurrence app binds container port 8210; juniper-deploy maps host 8211 -> 8210,
+# so the default host-facing base URL is 8211 (mirrors the deploy port map).
+DEFAULT_BASE_URL: str = "http://localhost:8211"
+
+# ─── HTTP Configuration ──────────────────────────────────────────────────────
+
+DEFAULT_TIMEOUT: int = 30
+DEFAULT_RETRIES: int = 3
+DEFAULT_BACKOFF_FACTOR: float = 0.5
+RETRYABLE_STATUS_CODES: List[int] = [429, 500, 502, 503, 504]
+# Auto-retry is restricted to idempotent methods (RFC 9110 §9.2.2). The recurrence POSTs
+# (train / predict / crossval) carry server-side state — train and crossval are lock-guarded —
+# so a transient-5xx retry must not silently re-issue them. Only GET/HEAD auto-retry.
+RETRY_ALLOWED_METHODS: List[str] = ["HEAD", "GET"]
+HTTP_POOL_CONNECTIONS: int = 10
+HTTP_POOL_MAXSIZE: int = 10
+
+# ─── URL Normalization ───────────────────────────────────────────────────────
+
+URL_SCHEME_PREFIXES: Tuple[str, ...] = ("http://", "https://")
+DEFAULT_URL_SCHEME_PREFIX: str = "http://"
+API_VERSION_PATH_SUFFIX: str = "/v1"
+
+# ─── Readiness Polling ───────────────────────────────────────────────────────
+
+DEFAULT_READY_TIMEOUT: float = 30.0
+DEFAULT_READY_POLL_INTERVAL: float = 0.5
+HEALTH_READY_STATUS: str = "ready"
+
+# ─── Authentication ──────────────────────────────────────────────────────────
+
+# The recurrence app enforces the X-API-Key header, reading its accepted keys from
+# JUNIPER_RECURRENCE_API_KEYS (plural; CSV or JSON array, with _FILE indirection). The client
+# sends a single key, resolved from the singular JUNIPER_RECURRENCE_API_KEY (and its _FILE
+# Docker-secret form) — document the singular/plural asymmetry in AGENTS.md.
+API_KEY_HEADER_NAME: str = "X-API-Key"
+API_KEY_ENV_VAR: str = "JUNIPER_RECURRENCE_API_KEY"
+API_KEY_FILE_ENV_VAR: str = f"{API_KEY_ENV_VAR}_FILE"
+
+# ─── REST Endpoints (the juniper-recurrence app surface) ─────────────────────
+
+ENDPOINT_HEALTH: str = "/v1/health"
+ENDPOINT_HEALTH_READY: str = "/v1/health/ready"
+ENDPOINT_TRAIN: str = "/v1/train"
+ENDPOINT_TRAINING_STATUS: str = "/v1/training/status"
+ENDPOINT_PREDICT: str = "/v1/predict"
+ENDPOINT_MODEL: str = "/v1/model"
+ENDPOINT_DATASET: str = "/v1/dataset"
+ENDPOINT_CROSSVAL: str = "/v1/crossval"
+ENDPOINT_CROSSVAL_STATUS: str = "/v1/crossval/status"
+
+# ─── HTTP Status Codes ───────────────────────────────────────────────────────
+
+HTTP_400_BAD_REQUEST: int = 400
+HTTP_404_NOT_FOUND: int = 404
+HTTP_409_CONFLICT: int = 409
+HTTP_422_UNPROCESSABLE_ENTITY: int = 422

juniper_recurrence_client-0.1.0/juniper_recurrence_client/exceptions.py

@@ -0,0 +1,36 @@
+"""Custom exceptions for the juniper-recurrence client library.
+
+Mirrors juniper-data-client's flat hierarchy (one base + typed leaves), adding a
+``JuniperRecurrenceConflictError`` for the recurrence app's ``409`` responses (a training /
+cross-validation run already in progress, or an operation that needs a trained model that does
+not yet exist) — a status the data-client surface never returns.
+"""
+
+
+class JuniperRecurrenceClientError(Exception):
+    """Base exception for all juniper-recurrence client errors."""
+
+
+class JuniperRecurrenceConnectionError(JuniperRecurrenceClientError):
+    """Raised when the connection to the juniper-recurrence service fails."""
+
+
+class JuniperRecurrenceTimeoutError(JuniperRecurrenceClientError):
+    """Raised when a request to the juniper-recurrence service times out."""
+
+
+class JuniperRecurrenceNotFoundError(JuniperRecurrenceClientError):
+    """Raised when a requested resource is not found (404)."""
+
+
+class JuniperRecurrenceValidationError(JuniperRecurrenceClientError):
+    """Raised when request parameters fail validation (400 / 422)."""
+
+
+class JuniperRecurrenceConflictError(JuniperRecurrenceClientError):
+    """Raised on a 409 Conflict — a training/cross-validation run is already in progress, or
+    the operation requires a trained model/dataset that does not yet exist."""
+
+
+class JuniperRecurrenceConfigurationError(JuniperRecurrenceClientError):
+    """Raised when juniper-recurrence client configuration is missing or invalid."""

juniper_recurrence_client-0.1.0/juniper_recurrence_client.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: juniper-recurrence-client
+Version: 0.1.0
+Summary: HTTP client for the juniper-recurrence service (the Δt-native LMU recurrence model + cross-validation API)
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Repository, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Issues, https://github.com/pcalnon/juniper-recurrence/issues
+Keywords: juniper,recurrence,lmu,http-client,rest,time-series,cross-validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: responses>=0.23; extra == "test"
+Provides-Extra: observability
+Requires-Dist: juniper-observability>=0.3.1; extra == "observability"
+
+# juniper-recurrence-client
+
+HTTP client for the **juniper-recurrence** service — the FastAPI app wrapping the Δt-native LMU
+recurrence model and its cross-validation API. A lean `requests`-based client mirroring
+[`juniper-data-client`](https://github.com/pcalnon/juniper-data-client) and
+[`juniper-cascor-client`](https://github.com/pcalnon/juniper-cascor-client), so consumers
+(notably **juniper-canopy**'s recurrence backend adapter) drive every Juniper backend the same way.
+
+## Install
+
+```bash
+pip install juniper-recurrence-client          # once published
+pip install -e ".[test]"                        # local development
+```
+
+`requests`-only at the core; `pip install juniper-recurrence-client[observability]` adds the
+optional `juniper-observability` integration (X-Request-ID propagation + the `on_request` hook).
+
+## Quick start
+
+```python
+from juniper_recurrence_client import JuniperRecurrenceClient
+
+client = JuniperRecurrenceClient("http://localhost:8211", api_key="…")
+
+# Train the LMU regressor on a dataset (by id / name / generator)
+client.train(name="equities", d=16)
+
+# Predict — inline X with Δt, or a dataset reference
+client.predict(dataset_id="ds-1")
+
+# Walk-forward cross-validation over the dataset's _full split
+result = client.crossval(name="equities", n_folds=4, scheme="expanding", embargo=2)
+print(result["eval_aggregate"])
+
+# Inspect
+client.get_model()        # topology + metrics
+client.training_status()  # state + events
+client.is_ready()         # readiness probe
+```
+
+## API surface
+
+| Method | Endpoint |
+|--------|----------|
+| `train(*, dataset_id / name / generator, params, split, d, theta, ridge)` | `POST /v1/train` |
+| `training_status()` | `GET /v1/training/status` |
+| `predict(*, X / dt / target_dt / seq_lengths, or a dataset ref)` | `POST /v1/predict` |
+| `crossval(*, n_folds, scheme, embargo, min_train, dataset ref, d, theta, ridge)` | `POST /v1/crossval` |
+| `crossval_status()` | `GET /v1/crossval/status` |
+| `get_model()` | `GET /v1/model` |
+| `get_dataset()` | `GET /v1/dataset` |
+| `health_check()` / `is_ready()` / `wait_for_ready()` | `GET /v1/health[/ready]` |
+
+## Authentication
+
+Pass `api_key=…`, or set `JUNIPER_RECURRENCE_API_KEY` (or the Docker-secret
+`JUNIPER_RECURRENCE_API_KEY_FILE`, a path whose stripped contents are the key). The key is sent
+as the `X-API-Key` header. Note the asymmetry: the **server** reads the *plural*
+`JUNIPER_RECURRENCE_API_KEYS` (its accepted set); the **client** sends one key under the
+*singular* env var.
+
+## Errors
+
+All errors derive from `JuniperRecurrenceClientError`: `JuniperRecurrenceConnectionError`,
+`JuniperRecurrenceTimeoutError`, `JuniperRecurrenceNotFoundError` (404),
+`JuniperRecurrenceConflictError` (409 — a run already in progress, or no trained model yet),
+`JuniperRecurrenceValidationError` (400/422), `JuniperRecurrenceConfigurationError`.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pcalnon/juniper-recurrence/blob/main/LICENSE).

juniper_recurrence_client-0.1.0/juniper_recurrence_client.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+juniper_recurrence_client/__init__.py
+juniper_recurrence_client/_version.py
+juniper_recurrence_client/client.py
+juniper_recurrence_client/constants.py
+juniper_recurrence_client/exceptions.py
+juniper_recurrence_client.egg-info/PKG-INFO
+juniper_recurrence_client.egg-info/SOURCES.txt
+juniper_recurrence_client.egg-info/dependency_links.txt
+juniper_recurrence_client.egg-info/requires.txt
+juniper_recurrence_client.egg-info/top_level.txt
+tests/test_auth.py
+tests/test_client.py
+tests/test_errors.py
+tests/test_extra.py

juniper_recurrence_client-0.1.0/juniper_recurrence_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

juniper_recurrence_client-0.1.0/juniper_recurrence_client.egg-info/requires.txt

@@ -0,0 +1,10 @@
+requests>=2.28.0
+urllib3>=2.0.0
+
+[observability]
+juniper-observability>=0.3.1
+
+[test]
+pytest>=8.0
+pytest-cov>=5.0
+responses>=0.23

juniper_recurrence_client-0.1.0/juniper_recurrence_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+juniper_recurrence_client

juniper_recurrence_client-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "juniper-recurrence-client"
+dynamic = ["version"]
+description = "HTTP client for the juniper-recurrence service (the Δt-native LMU recurrence model + cross-validation API)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Paul Calnon" }]
+keywords = ["juniper", "recurrence", "lmu", "http-client", "rest", "time-series", "cross-validation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "urllib3>=2.0.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "responses>=0.23",
+]
+# Opt-in: the X-Request-ID propagation + the on_request hook integrate with
+# juniper-observability, but the client never requires it (the import is guarded).
+observability = [
+    "juniper-observability>=0.3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/pcalnon/juniper-recurrence"
+Repository = "https://github.com/pcalnon/juniper-recurrence"
+Issues = "https://github.com/pcalnon/juniper-recurrence/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "juniper_recurrence_client._version.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["juniper_recurrence_client*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+# Ecosystem-standard autoload SIGSEGV defense (dash/playwright plugins are not used here).
+addopts = ["-ra", "--strict-markers", "--strict-config", "-p", "no:dash", "-p", "no:playwright"]
+
+[tool.ruff]
+line-length = 512
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "I", "N"]
+
+[tool.ruff.lint.per-file-ignores]
+# X is the standard ML design-matrix argument name (juniper-model-core's array contract);
+# pep8-naming N803's lowercase rule is a false positive on it (mirrors the model package).
+"juniper_recurrence_client/client.py" = ["N803"]

juniper_recurrence_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

juniper_recurrence_client-0.1.0/tests/test_auth.py

@@ -0,0 +1,50 @@
+"""API-key resolution tests (explicit arg, env var, ``_FILE`` Docker-secret, precedence)."""
+
+from __future__ import annotations
+
+import pytest
+
+from juniper_recurrence_client import JuniperRecurrenceClient
+from juniper_recurrence_client.constants import API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, API_KEY_HEADER_NAME
+
+BASE_URL = "http://x:8211"
+
+
+def test_explicit_api_key_sets_header() -> None:
+    client = JuniperRecurrenceClient(base_url=BASE_URL, api_key="secret-key")
+    assert client.session.headers[API_KEY_HEADER_NAME] == "secret-key"
+
+
+def test_no_api_key_leaves_header_unset() -> None:
+    client = JuniperRecurrenceClient(base_url=BASE_URL)
+    assert API_KEY_HEADER_NAME not in client.session.headers
+
+
+def test_api_key_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(API_KEY_ENV_VAR, "env-key")
+    client = JuniperRecurrenceClient(base_url=BASE_URL)
+    assert client.session.headers[API_KEY_HEADER_NAME] == "env-key"
+
+
+def test_file_indirection_beats_plain_env(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    key_file = tmp_path / "key.txt"
+    key_file.write_text("  file-key\n", encoding="utf-8")
+    monkeypatch.setenv(API_KEY_FILE_ENV_VAR, str(key_file))
+    monkeypatch.setenv(API_KEY_ENV_VAR, "env-key")
+    client = JuniperRecurrenceClient(base_url=BASE_URL)
+    assert client.session.headers[API_KEY_HEADER_NAME] == "file-key"
+
+
+def test_explicit_api_key_beats_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(API_KEY_ENV_VAR, "env-key")
+    client = JuniperRecurrenceClient(base_url=BASE_URL, api_key="explicit")
+    assert client.session.headers[API_KEY_HEADER_NAME] == "explicit"
+
+
+def test_empty_file_falls_back_to_plain_env(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    empty = tmp_path / "empty.txt"
+    empty.write_text("   \n", encoding="utf-8")
+    monkeypatch.setenv(API_KEY_FILE_ENV_VAR, str(empty))
+    monkeypatch.setenv(API_KEY_ENV_VAR, "env-key")
+    client = JuniperRecurrenceClient(base_url=BASE_URL)
+    assert client.session.headers[API_KEY_HEADER_NAME] == "env-key"

juniper_recurrence_client-0.1.0/tests/test_client.py

@@ -0,0 +1,116 @@
+"""Unit tests for ``JuniperRecurrenceClient`` (HTTP mocked with ``responses``)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import responses
+
+from juniper_recurrence_client import JuniperRecurrenceClient
+
+BASE_URL = "http://recurrence.test:8211"
+
+
+def _client(**kwargs: object) -> JuniperRecurrenceClient:
+    kwargs.setdefault("retries", 0)
+    return JuniperRecurrenceClient(base_url=BASE_URL, **kwargs)
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("http://recurrence.test:8211", "http://recurrence.test:8211"),
+        ("http://recurrence.test:8211/", "http://recurrence.test:8211"),
+        ("http://recurrence.test:8211/v1", "http://recurrence.test:8211"),
+        ("recurrence.test:8211", "http://recurrence.test:8211"),
+    ],
+)
+def test_normalize_url(raw: str, expected: str) -> None:
+    assert JuniperRecurrenceClient(base_url=raw).base_url == expected
+
+
+@responses.activate
+def test_train_posts_dataset_ref_and_hyperparams() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/train", json={"final_metrics": {"r2": 0.9}, "n_epochs": 1, "stopped_reason": None, "dataset": {}}, status=200)
+    out = _client().train(name="equities", d=16, theta=2.0, ridge=0.1)
+    assert out["final_metrics"]["r2"] == 0.9
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["dataset"] == {"split": "train", "name": "equities"}
+    assert sent["d"] == 16 and sent["theta"] == 2.0 and sent["ridge"] == 0.1
+
+
+@responses.activate
+def test_training_status() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/training/status", json={"state": "trained", "final_metrics": {"r2": 0.9}, "stopped_reason": None, "events": []}, status=200)
+    assert _client().training_status()["state"] == "trained"
+
+
+@responses.activate
+def test_predict_inline_x() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/predict", json={"predictions": [[1.0]], "shape": [1, 1]}, status=200)
+    out = _client().predict(X=[[[1.0, 2.0]]], dt=[[0.0]])
+    assert out["shape"] == [1, 1]
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["X"] == [[[1.0, 2.0]]] and sent["dt"] == [[0.0]] and "dataset" not in sent
+
+
+@responses.activate
+def test_predict_by_dataset_ref() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/predict", json={"predictions": [], "shape": [0, 1]}, status=200)
+    _client().predict(dataset_id="ds-1")
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["dataset"] == {"split": "train", "dataset_id": "ds-1"} and "X" not in sent
+
+
+@responses.activate
+def test_crossval_passes_config() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/crossval", json={"task_type": "regression", "n_folds": 3, "folds": [], "eval_aggregate": {}, "eval_std": {}, "dataset": {}}, status=200)
+    out = _client().crossval(name="equities", n_folds=3, scheme="rolling", embargo=2, min_train=10)
+    assert out["n_folds"] == 3
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["n_folds"] == 3 and sent["scheme"] == "rolling" and sent["embargo"] == 2 and sent["min_train"] == 10
+
+
+@responses.activate
+def test_crossval_status_model_dataset() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/crossval/status", json={"state": "done", "result": None}, status=200)
+    responses.add(responses.GET, f"{BASE_URL}/v1/model", json={"topology": {"model_type": "lmu"}, "metrics": {}}, status=200)
+    responses.add(responses.GET, f"{BASE_URL}/v1/dataset", json={"dataset_id": "ds-1", "split": "train"}, status=200)
+    c = _client()
+    assert c.crossval_status()["state"] == "done"
+    assert c.get_model()["topology"]["model_type"] == "lmu"
+    assert c.get_dataset()["dataset_id"] == "ds-1"
+
+
+@responses.activate
+def test_health_and_is_ready() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/health", json={"status": "ok"}, status=200)
+    responses.add(responses.GET, f"{BASE_URL}/v1/health/ready", json={"status": "ready"}, status=200)
+    c = _client()
+    assert c.health_check()["status"] == "ok"
+    assert c.is_ready() is True
+
+
+@responses.activate
+def test_is_ready_false_when_not_ready() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/health/ready", json={"status": "starting"}, status=200)
+    assert _client().is_ready() is False
+
+
+@responses.activate
+def test_on_request_hook_fires_once() -> None:
+    seen: list[tuple[str, object, object, object]] = []
+
+    def hook(method: str, url: str, status: object, duration_ms: float, error: object) -> None:
+        seen.append((method, url, status, error))
+
+    responses.add(responses.GET, f"{BASE_URL}/v1/model", json={"topology": {}, "metrics": {}}, status=200)
+    _client(on_request=hook).get_model()
+    assert len(seen) == 1
+    assert seen[0][0] == "GET" and seen[0][2] == 200 and seen[0][3] is None
+
+
+def test_context_manager_closes() -> None:
+    with _client() as client:
+        assert client.session is not None

juniper_recurrence_client-0.1.0/tests/test_errors.py

@@ -0,0 +1,63 @@
+"""HTTP/transport error-mapping tests (status code -> typed exception)."""
+
+from __future__ import annotations
+
+import pytest
+import responses
+
+from juniper_recurrence_client import (
+    JuniperRecurrenceClient,
+    JuniperRecurrenceClientError,
+    JuniperRecurrenceConflictError,
+    JuniperRecurrenceConnectionError,
+    JuniperRecurrenceNotFoundError,
+    JuniperRecurrenceValidationError,
+)
+
+BASE_URL = "http://recurrence.test:8211"
+
+
+def _client() -> JuniperRecurrenceClient:
+    return JuniperRecurrenceClient(base_url=BASE_URL, retries=0)
+
+
+@responses.activate
+def test_404_maps_to_not_found() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/model", json={"detail": "no model"}, status=404)
+    with pytest.raises(JuniperRecurrenceNotFoundError, match="no model"):
+        _client().get_model()
+
+
+@responses.activate
+def test_409_maps_to_conflict() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/train", json={"detail": "training already in progress"}, status=409)
+    with pytest.raises(JuniperRecurrenceConflictError, match="in progress"):
+        _client().train(name="equities")
+
+
+@responses.activate
+def test_422_maps_to_validation() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/crossval", json={"detail": "n_folds must be >= 2"}, status=422)
+    with pytest.raises(JuniperRecurrenceValidationError, match="n_folds"):
+        _client().crossval(name="equities", n_folds=1)
+
+
+@responses.activate
+def test_500_maps_to_client_error() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/dataset", json={"detail": "boom"}, status=500)
+    with pytest.raises(JuniperRecurrenceClientError, match="500"):
+        _client().get_dataset()
+
+
+@responses.activate
+def test_connection_error_maps() -> None:
+    # No response registered for this URL -> responses raises a ConnectionError.
+    with pytest.raises(JuniperRecurrenceConnectionError):
+        _client().get_model()
+
+
+@responses.activate
+def test_malformed_json_raises_client_error() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/dataset", body="not-json", status=200, content_type="application/json")
+    with pytest.raises(JuniperRecurrenceClientError, match="Malformed JSON"):
+        _client().get_dataset()

juniper_recurrence_client-0.1.0/tests/test_extra.py

@@ -0,0 +1,76 @@
+"""Extra coverage: timeout / generic-request-error mapping, full predict & crossval bodies,
+readiness polling (success + timeout), and the api-key file-read-error fallback."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import requests
+import responses
+
+from juniper_recurrence_client import (
+    JuniperRecurrenceClient,
+    JuniperRecurrenceClientError,
+    JuniperRecurrenceTimeoutError,
+)
+from juniper_recurrence_client.constants import API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, API_KEY_HEADER_NAME
+
+BASE_URL = "http://recurrence.test:8211"
+
+
+def _client(**kwargs: object) -> JuniperRecurrenceClient:
+    kwargs.setdefault("retries", 0)
+    return JuniperRecurrenceClient(base_url=BASE_URL, **kwargs)
+
+
+@responses.activate
+def test_timeout_maps_to_timeout_error() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/model", body=requests.exceptions.Timeout("slow"))
+    with pytest.raises(JuniperRecurrenceTimeoutError):
+        _client().get_model()
+
+
+@responses.activate
+def test_generic_request_exception_maps_to_client_error() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/dataset", body=requests.exceptions.RequestException("boom"))
+    with pytest.raises(JuniperRecurrenceClientError):
+        _client().get_dataset()
+
+
+@responses.activate
+def test_predict_full_aux_body() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/predict", json={"predictions": [], "shape": [0, 1]}, status=200)
+    _client().predict(X=[[[1.0]]], dt=[[0.0]], target_dt=[1.0], seq_lengths=[1])
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["target_dt"] == [1.0] and sent["seq_lengths"] == [1]
+
+
+@responses.activate
+def test_crossval_passes_hyperparams() -> None:
+    responses.add(responses.POST, f"{BASE_URL}/v1/crossval", json={"task_type": "regression", "n_folds": 2, "folds": [], "eval_aggregate": {}, "eval_std": {}, "dataset": {}}, status=200)
+    _client().crossval(generator="equities_seq", n_folds=2, d=8, theta=1.5, ridge=0.2)
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent["dataset"]["generator"] == "equities_seq"
+    assert sent["d"] == 8 and sent["theta"] == 1.5 and sent["ridge"] == 0.2
+
+
+@responses.activate
+def test_wait_for_ready_polls_until_ready() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/health/ready", json={"status": "starting"}, status=200)
+    responses.add(responses.GET, f"{BASE_URL}/v1/health/ready", json={"status": "ready"}, status=200)
+    assert _client().wait_for_ready(timeout=2.0, poll_interval=0.01) is True
+
+
+@responses.activate
+def test_wait_for_ready_times_out() -> None:
+    responses.add(responses.GET, f"{BASE_URL}/v1/health/ready", json={"status": "starting"}, status=200)
+    assert _client().wait_for_ready(timeout=0.03, poll_interval=0.01) is False
+
+
+def test_api_key_file_read_error_falls_back_to_env(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    # _FILE points at a missing path -> OSError on read -> fall back to the plain env var.
+    monkeypatch.setenv(API_KEY_FILE_ENV_VAR, str(tmp_path / "does-not-exist"))
+    monkeypatch.setenv(API_KEY_ENV_VAR, "env-key")
+    client = JuniperRecurrenceClient(base_url=BASE_URL)
+    assert client.session.headers[API_KEY_HEADER_NAME] == "env-key"