juniper-recurrence-client 0.1.0__py3-none-any.whl

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/_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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+juniper_recurrence_client/__init__.py,sha256=9syq9UcmxcaAUFKFdDFi0L0OfowLfLhH6Re_6M40184,1241
+juniper_recurrence_client/_version.py,sha256=G5N0gMJr16EzZkJxmZ_-331Ik5n1_GiAiwcdfH5yVBY,257
+juniper_recurrence_client/client.py,sha256=ThQ-lIxYiRj77q1L5kjoi0D6ddrN-LkWVi87cc9cTJw,18484
+juniper_recurrence_client/constants.py,sha256=dAjhsmj2FYoMoMZ9Bzgm_M0Kh--dhLgJ7HqLs_CpAIY,4370
+juniper_recurrence_client/exceptions.py,sha256=s35j9ptFLreRiKwJaTcxx5PqcMalqG9XWQwUDQ5wExY,1495
+juniper_recurrence_client-0.1.0.dist-info/METADATA,sha256=lGn4AThn9DMxFK9AyCRlvEENUtkuX72etiE_ld6S310,4457
+juniper_recurrence_client-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+juniper_recurrence_client-0.1.0.dist-info/top_level.txt,sha256=9vPOg7TzwR0LzObh6LovcuQClP5qPmMabSqEqjnoawo,26
+juniper_recurrence_client-0.1.0.dist-info/RECORD,,

juniper_recurrence_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

juniper_recurrence_client-0.1.0.dist-info/top_level.txt

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