juniper-data-client 0.4.0__tar.gz → 0.4.1__tar.gz

{juniper_data_client-0.4.0 → juniper_data_client-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: juniper-data-client
-Version: 0.4.0
+Version: 0.4.1
 Summary: HTTP client for the JuniperData dataset generation service
 Author: Paul Calnon
 License-Expression: MIT
@@ -31,6 +31,9 @@ Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.2.0; extra == "test"
 Requires-Dist: responses>=0.23.0; extra == "test"
+Requires-Dist: juniper-observability>=0.1.1; extra == "test"
+Provides-Extra: observability
+Requires-Dist: juniper-observability>=0.1.1; extra == "observability"
 Provides-Extra: dev
 Requires-Dist: juniper-data-client[test]; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"

{juniper_data_client-0.4.0 → juniper_data_client-0.4.1}/juniper_data_client/__init__.py

@@ -4,10 +4,10 @@ This package provides a simple, robust client for interacting with the JuniperDa
 dataset generation service, used by both JuniperCascor and juniper-canopy.
 """
 
-from juniper_data_client.client import JuniperDataClient
+from juniper_data_client.client import JuniperDataClient, RequestHook
 from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConfigurationError, JuniperDataConnectionError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 __all__ = [
     "JuniperDataClient",
@@ -17,5 +17,8 @@ __all__ = [
     "JuniperDataNotFoundError",
     "JuniperDataTimeoutError",
     "JuniperDataValidationError",
+    # METRICS-MON R4.3 / seed-13: instrumentation hook type alias
+    # exported so consumers can type their hook closures.
+    "RequestHook",
     "__version__",
 ]

{juniper_data_client-0.4.0 → juniper_data_client-0.4.1}/juniper_data_client/client.py

@@ -5,9 +5,10 @@ for JuniperCascor and juniper-canopy applications.
 """
 
 import io
+import logging
 import os
 import time
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 from urllib.parse import urlparse
 
 import numpy as np
@@ -15,8 +16,89 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
+from juniper_data_client.constants import (
+    API_KEY_ENV_VAR,
+    API_KEY_HEADER_NAME,
+    API_VERSION_PATH_SUFFIX,
+    DEFAULT_BACKOFF_FACTOR,
+    DEFAULT_BASE_URL,
+    DEFAULT_LIST_LIMIT,
+    DEFAULT_LIST_OFFSET,
+    DEFAULT_PREVIEW_N,
+    DEFAULT_READY_POLL_INTERVAL,
+    DEFAULT_READY_TIMEOUT,
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUT,
+    DEFAULT_URL_SCHEME_PREFIX,
+    ENDPOINT_BATCH_CREATE,
+    ENDPOINT_BATCH_DELETE,
+    ENDPOINT_BATCH_EXPORT,
+    ENDPOINT_BATCH_TAGS,
+    ENDPOINT_DATASET_ARTIFACT_TEMPLATE,
+    ENDPOINT_DATASET_BY_ID_TEMPLATE,
+    ENDPOINT_DATASET_PREVIEW_TEMPLATE,
+    ENDPOINT_DATASETS,
+    ENDPOINT_DATASETS_LATEST,
+    ENDPOINT_DATASETS_VERSIONS,
+    ENDPOINT_GENERATOR_SCHEMA_TEMPLATE,
+    ENDPOINT_GENERATORS,
+    ENDPOINT_HEALTH,
+    ENDPOINT_HEALTH_READY,
+    GENERATOR_SPIRAL,
+    HEALTH_READY_STATUS,
+    HTTP_400_BAD_REQUEST,
+    HTTP_404_NOT_FOUND,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_POOL_CONNECTIONS,
+    HTTP_POOL_MAXSIZE,
+    RETRY_ALLOWED_METHODS,
+    RETRYABLE_STATUS_CODES,
+    SPIRAL_ALGORITHM_DEFAULT,
+    SPIRAL_N_POINTS_PER_SPIRAL_DEFAULT,
+    SPIRAL_N_SPIRALS_DEFAULT,
+    SPIRAL_NOISE_DEFAULT,
+    SPIRAL_TRAIN_RATIO_DEFAULT,
+    URL_SCHEME_PREFIXES,
+)
 from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConnectionError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
 
+logger = logging.getLogger("juniper_data_client.client")
+
+
+# METRICS-MON R4.3 / seed-13: type alias for the optional instrumentation
+# hook. Consumers (canopy, cascor) pass a callable matching this shape;
+# default in :class:`JuniperDataClient` is no-op so standalone users
+# (notebooks, ad-hoc scripts) pay nothing for an unused hook.
+#
+# Fields:
+#   method     — HTTP method ("GET", "POST", ...).
+#   url        — absolute URL the request hit (post-base_url-join).
+#   status     — final HTTP status code, or None if no response was
+#                received (transport failure / timeout).
+#   duration_ms— wall-clock from issue to outcome, milliseconds.
+#   error      — exception instance on failure paths, or None on success.
+#                ``error is None`` is the canonical success signal —
+#                ``status`` may be set even on the error path (for
+#                JuniperDataValidationError, JuniperDataNotFoundError,
+#                etc.) so it's not a reliable success indicator.
+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.
+
+    Used when the consumer doesn't pass an ``on_request`` kwarg. The
+    no-op exists as a named symbol so test code (and IDE introspection)
+    can confirm the default is genuinely a callable that matches the
+    :data:`RequestHook` signature, not ``None``.
+    """
+
 
 class JuniperDataClient:
     """Client for interacting with the JuniperData REST API.
@@ -31,17 +113,14 @@ class JuniperDataClient:
         >>> X_train, y_train = arrays["X_train"], arrays["y_train"]
     """
 
-    DEFAULT_TIMEOUT = 30
-    DEFAULT_RETRIES = 3
-    DEFAULT_BACKOFF_FACTOR = 0.5
-
     def __init__(
         self,
-        base_url: str = "http://localhost:8100",
+        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,
     ):
         """Initialize the JuniperData client.
 
@@ -52,16 +131,29 @@ class JuniperDataClient:
             backoff_factor: Backoff factor for retry delays (default: 0.5)
             api_key: API key for authentication. If not provided, reads from
                 JUNIPER_DATA_API_KEY environment variable.
+            on_request: METRICS-MON R4.3 / seed-13 — optional
+                instrumentation hook invoked once per HTTP call with
+                ``(method, url, status, duration_ms, error)``. Default
+                is a no-op so standalone use pays nothing. Consumers
+                that need Prometheus / OpenTelemetry / structured-log
+                emission supply a closure (see canopy's adoption for
+                the canonical pattern). Hook exceptions are caught and
+                logged at WARNING — instrumentation must never crash a
+                production HTTP 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()
+        # METRICS-MON R4.3: store hook (defaulting to no-op rather than
+        # ``None`` so call sites don't need ``if self._on_request: ...``
+        # guards — the no-op call is a single attribute load + return).
+        self._on_request: RequestHook = on_request or _noop_request_hook
 
-        resolved_api_key = api_key or os.environ.get("JUNIPER_DATA_API_KEY")
+        resolved_api_key = api_key or os.environ.get(API_KEY_ENV_VAR)
         if resolved_api_key:
-            self.session.headers["X-API-Key"] = resolved_api_key
+            self.session.headers[API_KEY_HEADER_NAME] = resolved_api_key
 
     def _normalize_url(self, url: str) -> str:
         """Normalize the base URL for consistent API calls.
@@ -74,15 +166,15 @@ class JuniperDataClient:
         """
         url = url.strip()
 
-        if not url.startswith(("http://", "https://")):
-            url = f"http://{url}"
+        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}"
         normalized = normalized.rstrip("/")
 
-        if normalized.endswith("/v1"):
-            normalized = normalized[:-3]
+        if normalized.endswith(API_VERSION_PATH_SUFFIX):
+            normalized = normalized[: -len(API_VERSION_PATH_SUFFIX)]
 
         return normalized
 
@@ -97,22 +189,22 @@ class JuniperDataClient:
         retry_strategy = Retry(
             total=self.retries,
             backoff_factor=self.backoff_factor,
-            status_forcelist=[429, 500, 502, 503, 504],
-            allowed_methods=["HEAD", "GET", "POST", "PATCH", "DELETE"],
+            status_forcelist=RETRYABLE_STATUS_CODES,
+            allowed_methods=RETRY_ALLOWED_METHODS,
         )
 
         adapter = HTTPAdapter(
             max_retries=retry_strategy,
-            pool_connections=10,
-            pool_maxsize=10,
+            pool_connections=HTTP_POOL_CONNECTIONS,
+            pool_maxsize=HTTP_POOL_MAXSIZE,
         )
 
-        session.mount("http://", adapter)
-        session.mount("https://", adapter)
+        for scheme in URL_SCHEME_PREFIXES:
+            session.mount(scheme, adapter)
 
         return session
 
-    def _request(self, method: str, endpoint: str, **kwargs: Any) -> requests.Response:
+    def _request(self, method: str, endpoint: str, **kwargs: Any) -> requests.Response:  # noqa: C901
         """Make an HTTP request with error handling.
 
         Args:
@@ -133,34 +225,102 @@ class JuniperDataClient:
         url = f"{self.base_url}{endpoint}"
         kwargs.setdefault("timeout", self.timeout)
 
+        # METRICS-MON R4.6: opt-in propagation of the caller's request-id
+        # via the shared ``juniper-observability`` ContextVar. When the
+        # calling thread has a non-empty ``request_id_var``, copy it into
+        # an outbound ``X-Request-ID`` header so juniper-data can correlate
+        # the inbound request back to the caller's chain (canopy/cascor →
+        # data-client → data). The check is best-effort: if
+        # ``juniper-observability`` is not installed (e.g. data-client
+        # used standalone in a notebook), the propagation silently no-ops
+        # — data-side ``RequestIdMiddleware`` will generate a fresh id.
+        # Caller-supplied headers always win — if ``kwargs["headers"]``
+        # already contains ``X-Request-ID``, do not overwrite it.
+        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):
+                # ImportError: juniper-observability not installed (standalone use).
+                # LookupError: request_id_var ContextVar has no value in this thread.
+                # Both are expected; silently fall through.
+                pass
+
+        # METRICS-MON R4.3: instrumentation hook fires once per call,
+        # in the ``finally`` block so every outcome path is observed
+        # (success, transport error, HTTP non-2xx, all five typed
+        # exception branches). ``status`` carries the HTTP code when
+        # available; ``error`` carries the raised exception (or None on
+        # success). Hook exceptions are swallowed so instrumentation
+        # never crashes a production HTTP call.
+        start = time.monotonic()
+        response: Optional[requests.Response] = None
+        outgoing_error: Optional[BaseException] = None
         try:
-            response = self.session.request(method, url, **kwargs)
-        except requests.exceptions.ConnectionError as e:
-            raise JuniperDataConnectionError(f"Failed to connect to JuniperData at {self.base_url}: {e}") from e
-        except requests.exceptions.Timeout as e:
-            raise JuniperDataTimeoutError(f"Request to {url} timed out after {self.timeout}s: {e}") from e
-        except requests.exceptions.RequestException as e:
-            raise JuniperDataClientError(f"Request failed: {e}") 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):
-            # If the response body is not valid JSON or lacks a 'detail' field,
-            # fall back to using the raw response text as the error detail.
-            error_detail = response.text
+            try:
+                response = self.session.request(method, url, **kwargs)
+            except requests.exceptions.ConnectionError as e:
+                outgoing_error = JuniperDataConnectionError(f"Failed to connect to JuniperData at {self.base_url}: {e}")
+                raise outgoing_error from e
+            except requests.exceptions.Timeout as e:
+                outgoing_error = JuniperDataTimeoutError(f"Request to {url} timed out after {self.timeout}s: {e}")
+                raise outgoing_error from e
+            except requests.exceptions.RequestException as e:
+                outgoing_error = JuniperDataClientError(f"Request failed: {e}")
+                raise outgoing_error from e
+
+            if response.ok:
+                return response
 
-        if response.status_code == 404:
-            raise JuniperDataNotFoundError(f"Resource not found: {error_detail}")
-        elif response.status_code in (400, 422):
-            raise JuniperDataValidationError(f"Validation error: {error_detail}")
-        else:
-            raise JuniperDataClientError(f"Request failed ({response.status_code}): {error_detail}")
+            error_detail = response.text
+            try:
+                error_json = response.json()
+                if "detail" in error_json:
+                    error_detail = error_json["detail"]
+            except (ValueError, KeyError):
+                # If the response body is not valid JSON or lacks a 'detail' field,
+                # fall back to using the raw response text as the error detail.
+                error_detail = response.text
+
+            if response.status_code == HTTP_404_NOT_FOUND:
+                outgoing_error = JuniperDataNotFoundError(f"Resource not found: {error_detail}")
+                raise outgoing_error
+            elif response.status_code in (HTTP_400_BAD_REQUEST, HTTP_422_UNPROCESSABLE_ENTITY):
+                outgoing_error = JuniperDataValidationError(f"Validation error: {error_detail}")
+                raise outgoing_error
+            else:
+                outgoing_error = JuniperDataClientError(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 successful response body as JSON.
+
+        ERR-01 (Phase 4C): callers previously invoked ``response.json()`` directly,
+        which raises ``requests.exceptions.JSONDecodeError`` (a ``ValueError`` subclass)
+        on malformed bodies. Surface a typed ``JuniperDataClientError`` instead so the
+        public API never leaks a raw ``json.JSONDecodeError``.
+        """
+        try:
+            return response.json()
+        except ValueError as e:
+            preview = (response.text or "")[:200]
+            raise JuniperDataClientError(f"Malformed JSON response from {response.url}: {e}: {preview!r}") from e
 
     def health_check(self) -> Dict[str, Any]:
         """Check if the JuniperData service is healthy.
@@ -171,8 +331,8 @@ class JuniperDataClient:
         Raises:
             JuniperDataConnectionError: If service is unreachable
         """
-        response = self._request("GET", "/v1/health")
-        return response.json()
+        response = self._request("GET", ENDPOINT_HEALTH)
+        return self._parse_json(response)
 
     def is_ready(self) -> bool:
         """Check if the JuniperData service is ready to accept requests.
@@ -181,12 +341,12 @@ class JuniperDataClient:
             True if service is ready, False otherwise
         """
         try:
-            response = self._request("GET", "/v1/health/ready")
-            return response.json().get("status") == "ready"
+            response = self._request("GET", ENDPOINT_HEALTH_READY)
+            return self._parse_json(response).get("status") == HEALTH_READY_STATUS
         except JuniperDataClientError:
             return False
 
-    def wait_for_ready(self, timeout: float = 30.0, poll_interval: float = 0.5) -> bool:
+    def wait_for_ready(self, timeout: float = DEFAULT_READY_TIMEOUT, poll_interval: float = DEFAULT_READY_POLL_INTERVAL) -> bool:
         """Wait for the JuniperData service to become ready.
 
         Args:
@@ -209,8 +369,8 @@ class JuniperDataClient:
         Returns:
             List of generator information dictionaries
         """
-        response = self._request("GET", "/v1/generators")
-        return response.json()
+        response = self._request("GET", ENDPOINT_GENERATORS)
+        return self._parse_json(response)
 
     def get_generator_schema(self, name: str) -> Dict[str, Any]:
         """Get the parameter schema for a generator.
@@ -224,8 +384,8 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If generator not found
         """
-        response = self._request("GET", f"/v1/generators/{name}/schema")
-        return response.json()
+        response = self._request("GET", ENDPOINT_GENERATOR_SCHEMA_TEMPLATE.format(name=name))
+        return self._parse_json(response)
 
     def create_dataset(
         self,
@@ -236,6 +396,8 @@ class JuniperDataClient:
         description: Optional[str] = None,
         created_by: Optional[str] = None,
         parent_dataset_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        ttl_seconds: Optional[int] = None,
     ) -> Dict[str, Any]:
         """Create a new dataset via the JuniperData API.
 
@@ -251,6 +413,13 @@ class JuniperDataClient:
             description: Optional human-readable description of the dataset.
             created_by: Optional identifier for the creator (user or system).
             parent_dataset_id: Optional ID of the parent dataset this was derived from.
+            tags: Optional list of tag strings to attach to the dataset. Forwarded
+                to the server's ``CreateDatasetRequest.tags`` field. Server-side
+                tags are searchable via ``list_datasets`` filters.
+            ttl_seconds: Optional time-to-live in seconds (must be positive when
+                provided). After the TTL elapses the server is free to expire the
+                dataset via the cleanup-expired route. Mirrors
+                ``CreateDatasetRequest.ttl_seconds``.
 
         Returns:
             Parsed JSON response containing dataset_id, generator, meta, and artifact_url
@@ -272,9 +441,16 @@ class JuniperDataClient:
             payload["created_by"] = created_by
         if parent_dataset_id is not None:
             payload["parent_dataset_id"] = parent_dataset_id
+        # XREPO-09 (2026-04-24): previously dropped by the client; the
+        # server's CreateDatasetRequest has accepted these fields since
+        # juniper-data v0.6.0.
+        if tags is not None:
+            payload["tags"] = list(tags)
+        if ttl_seconds is not None:
+            payload["ttl_seconds"] = ttl_seconds
 
-        response = self._request("POST", "/v1/datasets", json=payload)
-        return response.json()
+        response = self._request("POST", ENDPOINT_DATASETS, json=payload)
+        return self._parse_json(response)
 
     def list_versions(self, name: str) -> Dict[str, Any]:
         """List all versions of a named dataset.
@@ -285,8 +461,8 @@ class JuniperDataClient:
         Returns:
             Dict with dataset_name, versions list, total count, and latest_version.
         """
-        response = self._request("GET", "/v1/datasets/versions", params={"name": name})
-        return response.json()
+        response = self._request("GET", ENDPOINT_DATASETS_VERSIONS, params={"name": name})
+        return self._parse_json(response)
 
     def get_latest(self, name: str) -> Dict[str, Any]:
         """Get the latest version of a named dataset.
@@ -300,10 +476,10 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If no versions exist for the given name.
         """
-        response = self._request("GET", "/v1/datasets/latest", params={"name": name})
-        return response.json()
+        response = self._request("GET", ENDPOINT_DATASETS_LATEST, params={"name": name})
+        return self._parse_json(response)
 
-    def list_datasets(self, limit: int = 100, offset: int = 0) -> List[str]:
+    def list_datasets(self, limit: int = DEFAULT_LIST_LIMIT, offset: int = DEFAULT_LIST_OFFSET) -> List[str]:
         """List dataset IDs.
 
         Args:
@@ -313,8 +489,8 @@ class JuniperDataClient:
         Returns:
             List of dataset ID strings
         """
-        response = self._request("GET", "/v1/datasets", params={"limit": limit, "offset": offset})
-        return response.json()
+        response = self._request("GET", ENDPOINT_DATASETS, params={"limit": limit, "offset": offset})
+        return self._parse_json(response)
 
     def get_dataset_metadata(self, dataset_id: str) -> Dict[str, Any]:
         """Get metadata for a specific dataset.
@@ -328,8 +504,8 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If dataset not found
         """
-        response = self._request("GET", f"/v1/datasets/{dataset_id}")
-        return response.json()
+        response = self._request("GET", ENDPOINT_DATASET_BY_ID_TEMPLATE.format(dataset_id=dataset_id))
+        return self._parse_json(response)
 
     def download_artifact_bytes(self, dataset_id: str) -> bytes:
         """Download the raw NPZ artifact bytes for a dataset.
@@ -343,7 +519,7 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If dataset not found
         """
-        response = self._request("GET", f"/v1/datasets/{dataset_id}/artifact")
+        response = self._request("GET", ENDPOINT_DATASET_ARTIFACT_TEMPLATE.format(dataset_id=dataset_id))
         return response.content
 
     def download_artifact_npz(self, dataset_id: str) -> Dict[str, np.ndarray]:
@@ -366,10 +542,17 @@ class JuniperDataClient:
             JuniperDataNotFoundError: If dataset not found
         """
         content = self.download_artifact_bytes(dataset_id)
-        npz_file = np.load(io.BytesIO(content))
-        return {key: npz_file[key] for key in npz_file.files}
-
-    def get_preview(self, dataset_id: str, n: int = 100) -> Dict[str, Any]:
+        # CC-07 (Phase 4E): np.load returns an NpzFile that holds an open
+        # ZipFile backed by the BytesIO. Without context-managing it the
+        # underlying file handle leaks until garbage collection runs, which
+        # in long-running clients accumulates ResourceWarning entries and
+        # can exhaust file-descriptor limits. Materialising the arrays
+        # inside the with-block lets us hand back plain numpy arrays while
+        # the NpzFile is closed deterministically.
+        with np.load(io.BytesIO(content)) as npz_file:
+            return {key: np.asarray(npz_file[key]) for key in npz_file.files}
+
+    def get_preview(self, dataset_id: str, n: int = DEFAULT_PREVIEW_N) -> Dict[str, Any]:
         """Get a preview of dataset samples as JSON.
 
         Args:
@@ -382,8 +565,8 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If dataset not found
         """
-        response = self._request("GET", f"/v1/datasets/{dataset_id}/preview", params={"n": n})
-        return response.json()
+        response = self._request("GET", ENDPOINT_DATASET_PREVIEW_TEMPLATE.format(dataset_id=dataset_id), params={"n": n})
+        return self._parse_json(response)
 
     def delete_dataset(self, dataset_id: str) -> bool:
         """Delete a dataset.
@@ -397,17 +580,17 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If dataset not found
         """
-        self._request("DELETE", f"/v1/datasets/{dataset_id}")
+        self._request("DELETE", ENDPOINT_DATASET_BY_ID_TEMPLATE.format(dataset_id=dataset_id))
         return True
 
     def create_spiral_dataset(
         self,
-        n_spirals: int = 2,
-        n_points_per_spiral: int = 100,
-        noise: float = 0.1,
+        n_spirals: int = SPIRAL_N_SPIRALS_DEFAULT,
+        n_points_per_spiral: int = SPIRAL_N_POINTS_PER_SPIRAL_DEFAULT,
+        noise: float = SPIRAL_NOISE_DEFAULT,
         seed: Optional[int] = None,
-        algorithm: str = "modern",
-        train_ratio: float = 0.8,
+        algorithm: str = SPIRAL_ALGORITHM_DEFAULT,
+        train_ratio: float = SPIRAL_TRAIN_RATIO_DEFAULT,
         **kwargs: Any,
     ) -> Dict[str, Any]:
         """Convenience method for creating spiral datasets.
@@ -435,7 +618,7 @@ class JuniperDataClient:
             params["seed"] = seed
         params.update(kwargs)
 
-        return self.create_dataset("spiral", params)
+        return self.create_dataset(GENERATOR_SPIRAL, params)
 
     # ─── Batch Operations ────────────────────────────────────────────────
 
@@ -448,8 +631,8 @@ class JuniperDataClient:
         Returns:
             Dictionary with deleted, not_found, and total_deleted.
         """
-        response = self._request("POST", "/v1/datasets/batch-delete", json={"dataset_ids": dataset_ids})
-        return response.json()
+        response = self._request("POST", ENDPOINT_BATCH_DELETE, json={"dataset_ids": dataset_ids})
+        return self._parse_json(response)
 
     def batch_create(self, datasets: List[Dict[str, Any]]) -> Dict[str, Any]:
         """Create multiple datasets in a single request.
@@ -463,8 +646,8 @@ class JuniperDataClient:
         Returns:
             Dictionary with results, total_created, and total_failed.
         """
-        response = self._request("POST", "/v1/datasets/batch-create", json={"datasets": datasets})
-        return response.json()
+        response = self._request("POST", ENDPOINT_BATCH_CREATE, json={"datasets": datasets})
+        return self._parse_json(response)
 
     def batch_update_tags(
         self,
@@ -487,8 +670,8 @@ class JuniperDataClient:
             payload["add_tags"] = add_tags
         if remove_tags:
             payload["remove_tags"] = remove_tags
-        response = self._request("PATCH", "/v1/datasets/batch-tags", json=payload)
-        return response.json()
+        response = self._request("PATCH", ENDPOINT_BATCH_TAGS, json=payload)
+        return self._parse_json(response)
 
     def batch_export(self, dataset_ids: List[str]) -> bytes:
         """Export multiple datasets as a ZIP archive of NPZ files.
@@ -502,7 +685,7 @@ class JuniperDataClient:
         Raises:
             JuniperDataNotFoundError: If none of the datasets exist.
         """
-        response = self._request("POST", "/v1/datasets/batch-export", json={"dataset_ids": dataset_ids})
+        response = self._request("POST", ENDPOINT_BATCH_EXPORT, json={"dataset_ids": dataset_ids})
         return response.content
 
     def close(self) -> None: