juniper-data-client 0.4.2__tar.gz → 0.5.0__tar.gz

juniper_data_client-0.5.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: juniper-data-client
+Version: 0.5.0
+Summary: HTTP client for the JuniperData dataset generation service
+Author: Paul Calnon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-data-client
+Project-URL: Repository, https://github.com/pcalnon/juniper-data-client
+Project-URL: Documentation, https://github.com/pcalnon/juniper-data-client#readme
+Project-URL: Issues, https://github.com/pcalnon/juniper-data-client/issues
+Keywords: juniper,juniper-ml,juniper-ai,artificial-intelligence,dataset,machine-learning,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: test
+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"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Dynamic: license-file
+
+# juniper-data-client
+
+[![PyPI](https://img.shields.io/pypi/v/juniper-data-client)](https://pypi.org/project/juniper-data-client/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+**Python HTTP client for the juniper-data dataset-generation service.**
+
+`juniper-data-client` is a thin, synchronous HTTP client for fetching datasets from a `juniper-data`
+instance. It exposes a single `JuniperDataClient` class whose methods correspond to the REST surface:
+generator schemas, dataset creation, tag-based filtering, batch operations, the named-version
+registry, and download of the resulting NPZ artifacts as ready-to-train `numpy` arrays. It is the
+canonical dataset-fetch interface used by `juniper-cascor` (training) and `juniper-canopy`
+(visualisation), and it reads the platform's shared `X_train` / `y_train` / `X_val` / `y_val` /
+`X_test` / `y_test` NPZ schema (all `float32`). `val` is
+presence-conditional: `validate_npz_contract` skips a split the artifact does not
+carry. Fake producers emit it (#187); live artifacts may omit it.
+
+> **Part of the Juniper platform.** juniper-data-client is the Python HTTP client for the juniper-data
+> dataset service in [Juniper](https://github.com/pcalnon/juniper-ml) — a multi-package ML research
+> platform built around constructive (Cascade-Correlation) and recurrent neural networks. Point it at
+> any running juniper-data instance.
+
+## Install
+
+```bash
+pip install juniper-data-client
+```
+
+Optional extras: `[observability]` adds X-Request-ID propagation via `juniper-observability`; `[test]`
+and `[dev]` install the test and lint/type-check toolchains.
+
+## Quick start
+
+```python
+from juniper_data_client import JuniperDataClient
+
+with JuniperDataClient("http://localhost:8100") as client:
+    print(client.health_check()["status"])
+
+    result = client.create_spiral_dataset(n_spirals=2, n_points_per_spiral=100, noise=0.1, seed=42)
+    arrays = client.download_artifact_npz(result["dataset_id"])
+
+    print("train:", len(arrays["X_train"]), "test:", len(arrays["X_test"]))
+```
+
+The artifacts come back as a dict of `float32` `numpy` arrays, ready for `torch.from_numpy(...)`.
+
+## API
+
+| Method | Purpose |
+|--------|---------|
+| `health_check()` / `is_ready()` / `wait_for_ready(...)` | Liveness / readiness probes |
+| `list_generators()` / `get_generator_schema(name)` | Discover available generators + their schemas |
+| `create_dataset(generator, params, ...)` | Create a dataset from any generator |
+| `create_spiral_dataset(...)` | Convenience wrapper for the spiral generator |
+| `download_artifact_npz(dataset_id)` / `download_artifact_bytes(dataset_id)` | Download as numpy arrays / raw bytes |
+| `get_dataset_metadata(id)` / `get_preview(id, n)` / `delete_dataset(id)` | Inspect / preview / delete |
+| `list_datasets(limit, offset)` | Paginated dataset listing |
+| `list_versions(name)` / `get_latest(name)` | Named-version registry |
+| `batch_create(...)` / `batch_delete(...)` / `batch_update_tags(...)` / `batch_export(...)` | Batch operations |
+
+## Status
+
+**Beta** on PyPI. The current version is shown by the badge above; see [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Documentation
+
+- [`docs/QUICK_START.md`](./docs/QUICK_START.md) — installation and verification guide
+- [`docs/REFERENCE.md`](./docs/REFERENCE.md) — full API reference, configuration, and error model
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

juniper_data_client-0.5.0/README.md

@@ -0,0 +1,74 @@
+# juniper-data-client
+
+[![PyPI](https://img.shields.io/pypi/v/juniper-data-client)](https://pypi.org/project/juniper-data-client/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+**Python HTTP client for the juniper-data dataset-generation service.**
+
+`juniper-data-client` is a thin, synchronous HTTP client for fetching datasets from a `juniper-data`
+instance. It exposes a single `JuniperDataClient` class whose methods correspond to the REST surface:
+generator schemas, dataset creation, tag-based filtering, batch operations, the named-version
+registry, and download of the resulting NPZ artifacts as ready-to-train `numpy` arrays. It is the
+canonical dataset-fetch interface used by `juniper-cascor` (training) and `juniper-canopy`
+(visualisation), and it reads the platform's shared `X_train` / `y_train` / `X_val` / `y_val` /
+`X_test` / `y_test` NPZ schema (all `float32`). `val` is
+presence-conditional: `validate_npz_contract` skips a split the artifact does not
+carry. Fake producers emit it (#187); live artifacts may omit it.
+
+> **Part of the Juniper platform.** juniper-data-client is the Python HTTP client for the juniper-data
+> dataset service in [Juniper](https://github.com/pcalnon/juniper-ml) — a multi-package ML research
+> platform built around constructive (Cascade-Correlation) and recurrent neural networks. Point it at
+> any running juniper-data instance.
+
+## Install
+
+```bash
+pip install juniper-data-client
+```
+
+Optional extras: `[observability]` adds X-Request-ID propagation via `juniper-observability`; `[test]`
+and `[dev]` install the test and lint/type-check toolchains.
+
+## Quick start
+
+```python
+from juniper_data_client import JuniperDataClient
+
+with JuniperDataClient("http://localhost:8100") as client:
+    print(client.health_check()["status"])
+
+    result = client.create_spiral_dataset(n_spirals=2, n_points_per_spiral=100, noise=0.1, seed=42)
+    arrays = client.download_artifact_npz(result["dataset_id"])
+
+    print("train:", len(arrays["X_train"]), "test:", len(arrays["X_test"]))
+```
+
+The artifacts come back as a dict of `float32` `numpy` arrays, ready for `torch.from_numpy(...)`.
+
+## API
+
+| Method | Purpose |
+|--------|---------|
+| `health_check()` / `is_ready()` / `wait_for_ready(...)` | Liveness / readiness probes |
+| `list_generators()` / `get_generator_schema(name)` | Discover available generators + their schemas |
+| `create_dataset(generator, params, ...)` | Create a dataset from any generator |
+| `create_spiral_dataset(...)` | Convenience wrapper for the spiral generator |
+| `download_artifact_npz(dataset_id)` / `download_artifact_bytes(dataset_id)` | Download as numpy arrays / raw bytes |
+| `get_dataset_metadata(id)` / `get_preview(id, n)` / `delete_dataset(id)` | Inspect / preview / delete |
+| `list_datasets(limit, offset)` | Paginated dataset listing |
+| `list_versions(name)` / `get_latest(name)` | Named-version registry |
+| `batch_create(...)` / `batch_delete(...)` / `batch_update_tags(...)` / `batch_export(...)` | Batch operations |
+
+## Status
+
+**Beta** on PyPI. The current version is shown by the badge above; see [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Documentation
+
+- [`docs/QUICK_START.md`](./docs/QUICK_START.md) — installation and verification guide
+- [`docs/REFERENCE.md`](./docs/REFERENCE.md) — full API reference, configuration, and error model
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

{juniper_data_client-0.4.2 → juniper_data_client-0.5.0}/juniper_data_client/__init__.py

@@ -5,10 +5,11 @@ dataset generation service, used by both JuniperCascor and juniper-canopy.
 """
 
 from juniper_data_client.client import JuniperDataClient, RequestHook
+from juniper_data_client.constants import ContractKind
 from juniper_data_client.contract import validate_npz_contract
-from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConfigurationError, JuniperDataConnectionError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
+from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConfigurationError, JuniperDataConnectionError, JuniperDataContractError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
 __all__ = [
     "JuniperDataClient",
@@ -16,11 +17,15 @@ __all__ = [
     "JuniperDataClientError",
     "JuniperDataConfigurationError",
     "JuniperDataConnectionError",
+    "JuniperDataContractError",
     "JuniperDataNotFoundError",
     "JuniperDataTimeoutError",
     "JuniperDataValidationError",
     # METRICS-MON R4.3 / seed-13: instrumentation hook type alias
     # exported so consumers can type their hook closures.
     "RequestHook",
+    # APD-DCLIENT-006: the validate_npz_contract return Literal, exported so
+    # consumers can annotate and exhaustively match on the result.
+    "ContractKind",
     "__version__",
 ]

{juniper_data_client-0.4.2 → juniper_data_client-0.5.0}/juniper_data_client/client.py

@@ -23,6 +23,7 @@ from juniper_data_client.constants import (
     API_KEY_HEADER_NAME,
     API_VERSION_PATH_SUFFIX,
     DEFAULT_BACKOFF_FACTOR,
+    DEFAULT_BACKOFF_JITTER,
     DEFAULT_BASE_URL,
     DEFAULT_LIST_LIMIT,
     DEFAULT_LIST_OFFSET,
@@ -62,7 +63,7 @@ from juniper_data_client.constants import (
     SPIRAL_TRAIN_RATIO_DEFAULT,
     URL_SCHEME_PREFIXES,
 )
-from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConnectionError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
+from juniper_data_client.exceptions import JuniperDataClientError, JuniperDataConfigurationError, JuniperDataConnectionError, JuniperDataNotFoundError, JuniperDataTimeoutError, JuniperDataValidationError
 
 logger = logging.getLogger("juniper_data_client.client")
 
@@ -122,6 +123,42 @@ def _noop_request_hook(
     """
 
 
+def _render_error_detail(detail: Any) -> str:
+    """Render a server ``detail`` payload as readable text for an error message.
+
+    FastAPI answers a validation failure with a *list* of error objects, e.g.::
+
+        [{"type": "missing", "loc": ["body", "seed"], "msg": "Field required"}]
+
+    Interpolating that list into an f-string produced a Python repr -- valid
+    text, but nothing a caller could parse and nothing a human could read at a
+    glance (defect-register ``APD-DCLIENT-003``). This renders the same content
+    as ``body.seed: Field required``, while the untouched structure stays
+    available on ``exc.detail``.
+
+    Anything that is not a list of mappings is returned via ``str`` unchanged,
+    so plain-string details and unexpected shapes both survive intact.
+    """
+    if not isinstance(detail, list):
+        return str(detail)
+
+    rendered: list[str] = []
+    for item in detail:
+        if not isinstance(item, dict):
+            rendered.append(str(item))
+            continue
+        msg = item.get("msg", "")
+        loc = item.get("loc")
+        if isinstance(loc, (list, tuple)) and loc:
+            location = ".".join(str(part) for part in loc)
+            rendered.append(f"{location}: {msg}" if msg else location)
+        else:
+            rendered.append(str(msg) if msg else str(item))
+    # An empty list is a degenerate but legal payload; ``str`` keeps it visible
+    # rather than collapsing it to an empty message.
+    return "; ".join(rendered) if rendered else str(detail)
+
+
 class JuniperDataClient:
     """Client for interacting with the JuniperData REST API.
 
@@ -185,13 +222,28 @@ class JuniperDataClient:
 
         Returns:
             Normalized URL with scheme, no trailing slash, no /v1 suffix
+
+        Raises:
+            JuniperDataConfigurationError: when the URL carries no host (an
+                empty string, a bare scheme, a path-only value, or a
+                userinfo-only authority like ``http://user:secret@``) — a
+                misconfiguration that would otherwise normalize to a broken,
+                hostless URL and fail opaquely on the first request
+                (``APD-DCLIENT-004``; mirrors juniper-recurrence-client).
         """
         url = url.strip()
 
-        if not url.startswith(URL_SCHEME_PREFIXES):
+        # Scheme matching is case-insensitive (RFC 3986 §3.1): a case-sensitive
+        # startswith would re-prefix "HTTPS://host" into "http://HTTPS://host",
+        # silently downgrading TLS and sending the API key to hostname "https".
+        if not url.lower().startswith(URL_SCHEME_PREFIXES):
             url = f"{DEFAULT_URL_SCHEME_PREFIX}{url}"
 
         parsed = urlparse(url)
+        # hostname, not netloc: netloc accepts a userinfo-only authority
+        # ("user:secret@") as truthy while hostname is None for it.
+        if not parsed.hostname:
+            raise JuniperDataConfigurationError(f"base_url must include a host; got {url!r}")
         normalized = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
         normalized = normalized.rstrip("/")
 
@@ -211,6 +263,8 @@ class JuniperDataClient:
         retry_strategy = Retry(
             total=self.retries,
             backoff_factor=self.backoff_factor,
+            # APD-ECO-002: decorrelate retry schedules across client instances.
+            backoff_jitter=DEFAULT_BACKOFF_JITTER,
             status_forcelist=RETRYABLE_STATUS_CODES,
             allowed_methods=RETRY_ALLOWED_METHODS,
         )
@@ -309,14 +363,46 @@ class JuniperDataClient:
                 # fall back to using the raw response text as the error detail.
                 error_detail = response.text
 
+            # APD-DCLIENT-003: ``error_detail`` is whatever the server sent --
+            # a str for most handlers, but a list[dict] for FastAPI's 422. It is
+            # attached to the exception UNMODIFIED, and rendered separately for
+            # the human-readable message. Interpolating the list directly
+            # produced a Python repr no caller could parse, and which lost
+            # nothing only because there was nowhere else for the structure to
+            # go. Now there is: ``exc.detail``.
+            rendered_detail = _render_error_detail(error_detail)
+
+            # The context is passed explicitly at each site rather than unpacked
+            # from a shared ``**kwargs`` dict: mypy --strict infers such a dict
+            # as ``dict[str, object]`` and cannot match it against the typed
+            # keyword-only parameters, so the dict form silently gives up the
+            # type checking on exactly the arguments being added here.
             if response.status_code == HTTP_404_NOT_FOUND:
-                outgoing_error = JuniperDataNotFoundError(f"Resource not found: {error_detail}")
+                outgoing_error = JuniperDataNotFoundError(
+                    f"Resource not found: {rendered_detail}",
+                    status_code=response.status_code,
+                    detail=error_detail,
+                    response=response,
+                )
                 raise outgoing_error
             elif response.status_code in (HTTP_400_BAD_REQUEST, HTTP_422_UNPROCESSABLE_ENTITY):
-                outgoing_error = JuniperDataValidationError(f"Validation error: {error_detail}")
+                # APD-DCLIENT-001: the status code is what separates these two.
+                # It rides on the exception now, so a caller no longer has to
+                # substring-match the message to tell them apart.
+                outgoing_error = JuniperDataValidationError(
+                    f"Validation error ({response.status_code}): {rendered_detail}",
+                    status_code=response.status_code,
+                    detail=error_detail,
+                    response=response,
+                )
                 raise outgoing_error
             else:
-                outgoing_error = JuniperDataClientError(f"Request failed ({response.status_code}): {error_detail}")
+                outgoing_error = JuniperDataClientError(
+                    f"Request failed ({response.status_code}): {rendered_detail}",
+                    status_code=response.status_code,
+                    detail=error_detail,
+                    response=response,
+                )
                 raise outgoing_error
         finally:
             duration_ms = (time.monotonic() - start) * 1000.0
@@ -413,6 +499,7 @@ class JuniperDataClient:
         self,
         generator: str,
         params: Dict[str, Any],
+        *,
         persist: bool = True,
         name: Optional[str] = None,
         description: Optional[str] = None,
@@ -423,6 +510,12 @@ class JuniperDataClient:
     ) -> Dict[str, Any]:
         """Create a new dataset via the JuniperData API.
 
+        ``persist`` and everything after it are keyword-only (defect-register
+        ``APD-DCLIENT-008``): with nine positional-or-keyword parameters the
+        call ``create_dataset("spiral", p, False)`` was legal and unreadable,
+        and any signature reordering would silently rebind arguments. Only
+        ``generator`` and ``params`` — the universal pair — stay positional.
+
         If a dataset with the same parameters already exists, the existing
         dataset is returned (caching behavior).
 
@@ -551,7 +644,6 @@ class JuniperDataClient:
         artifacts carry the standard keys:
         - X_train, y_train: Training features and one-hot labels
         - X_test, y_test: Test features and one-hot labels
-        - X_full, y_full: Full dataset features and one-hot labels
 
         Additional keys may be present depending on the generator (WS-1 /
         juniper-data#168):

{juniper_data_client-0.4.2 → juniper_data_client-0.5.0}/juniper_data_client/constants.py

@@ -9,18 +9,26 @@ Project: Juniper
 Sub-Project: juniper-data-client
 Application: JuniperDataClient
 Author: Paul Calnon
-Version: 0.4.0
+Version: 0.5.0
 License: MIT License
 """
 
-from typing import List, Tuple
+from typing import Final, List, Literal, Tuple
 
+# Complete export surface: every public module-level constant, in file order,
+# grouped by the section headers below. Completeness is enforced by
+# tests/test_constants_all_drift.py — a new constant that is not added here
+# fails that gate (and, on any module WITH __all__, CodeQL flags touched
+# non-exported globals as py/unused-global-variable, blocking the merge).
 __all__ = [
+    # Service Configuration
     "DEFAULT_BASE_URL",
     "FAKE_BASE_URL",
+    # HTTP Configuration
     "DEFAULT_TIMEOUT",
     "DEFAULT_RETRIES",
     "DEFAULT_BACKOFF_FACTOR",
+    "DEFAULT_BACKOFF_JITTER",
     "RETRYABLE_STATUS_CODES",
     "RETRY_ALLOWED_METHODS",
     "HTTP_POOL_CONNECTIONS",
@@ -28,12 +36,15 @@ __all__ = [
     "URL_SCHEME_PREFIXES",
     "DEFAULT_URL_SCHEME_PREFIX",
     "API_VERSION_PATH_SUFFIX",
+    # Readiness Polling
     "DEFAULT_READY_TIMEOUT",
     "DEFAULT_READY_POLL_INTERVAL",
     "HEALTH_READY_STATUS",
+    # Authentication
     "API_KEY_HEADER_NAME",
     "API_KEY_ENV_VAR",
     "API_KEY_FILE_ENV_VAR",
+    # REST Endpoints
     "ENDPOINT_HEALTH",
     "ENDPOINT_HEALTH_READY",
     "ENDPOINT_GENERATORS",
@@ -43,6 +54,133 @@ __all__ = [
     "ENDPOINT_DATASETS_LATEST",
     "ENDPOINT_DATASET_BY_ID_TEMPLATE",
     "ENDPOINT_DATASET_ARTIFACT_TEMPLATE",
+    "ENDPOINT_DATASET_PREVIEW_TEMPLATE",
+    "ENDPOINT_BATCH_CREATE",
+    "ENDPOINT_BATCH_DELETE",
+    "ENDPOINT_BATCH_TAGS",
+    "ENDPOINT_BATCH_EXPORT",
+    # HTTP Status Codes
+    "HTTP_400_BAD_REQUEST",
+    "HTTP_404_NOT_FOUND",
+    "HTTP_422_UNPROCESSABLE_ENTITY",
+    # Listing Defaults
+    "DEFAULT_LIST_LIMIT",
+    "DEFAULT_LIST_OFFSET",
+    # Preview Defaults
+    "DEFAULT_PREVIEW_N",
+    "MAX_PREVIEW_N",
+    # Data Type Contract
+    "DEFAULT_ARRAY_DTYPE",
+    # Generator Names
+    "GENERATOR_SPIRAL",
+    "GENERATOR_XOR",
+    "GENERATOR_CIRCLE",
+    "GENERATOR_CIRCLE_LEGACY",
+    "GENERATOR_MOON",
+    "GENERATOR_GAUSSIAN",
+    "GENERATOR_CHECKERBOARD",
+    "GENERATOR_CSV_IMPORT",
+    "GENERATOR_MNIST",
+    "GENERATOR_ARC_AGI",
+    "GENERATOR_EQUITIES",
+    "GENERATOR_EQUITIES_SEQ",
+    "GENERATOR_MULTI_SINE",
+    "GENERATOR_MACKEY_GLASS",
+    "GENERATOR_AR_P",
+    "GENERATOR_IRREGULAR_SINE",
+    "GENERATOR_DELAY_PRODUCT",
+    # Generator Catalog Metadata
+    "GENERATOR_VERSION",
+    "GENERATOR_DESCRIPTION_SPIRAL",
+    "GENERATOR_DESCRIPTION_XOR",
+    "GENERATOR_DESCRIPTION_CIRCLE",
+    "GENERATOR_DESCRIPTION_MOON",
+    "GENERATOR_DESCRIPTION_GAUSSIAN",
+    "GENERATOR_DESCRIPTION_CHECKERBOARD",
+    "GENERATOR_DESCRIPTION_CSV_IMPORT",
+    "GENERATOR_DESCRIPTION_MNIST",
+    "GENERATOR_DESCRIPTION_ARC_AGI",
+    "GENERATOR_DESCRIPTION_EQUITIES",
+    "GENERATOR_DESCRIPTION_EQUITIES_SEQ",
+    "GENERATOR_DESCRIPTION_MULTI_SINE",
+    "GENERATOR_DESCRIPTION_MACKEY_GLASS",
+    "GENERATOR_DESCRIPTION_AR_P",
+    "GENERATOR_DESCRIPTION_IRREGULAR_SINE",
+    "GENERATOR_DESCRIPTION_DELAY_PRODUCT",
+    # Generator Defaults — Spiral
+    "SPIRAL_N_SPIRALS_DEFAULT",
+    "SPIRAL_N_POINTS_PER_SPIRAL_DEFAULT",
+    "SPIRAL_NOISE_DEFAULT",
+    "SPIRAL_ALGORITHM_DEFAULT",
+    "SPIRAL_TRAIN_RATIO_DEFAULT",
+    "SPIRAL_N_SPIRALS_MIN",
+    "SPIRAL_N_POINTS_PER_SPIRAL_MIN",
+    "SPIRAL_NOISE_MIN",
+    "SPIRAL_TRAIN_RATIO_MIN",
+    "SPIRAL_TRAIN_RATIO_MAX",
+    "SPIRAL_ALGORITHM_MODERN",
+    "SPIRAL_ALGORITHM_LEGACY",
+    "SPIRAL_ALGORITHMS",
+    "SPIRAL_RADIUS_SCALE",
+    "SPIRAL_ANGLE_TURNS",
+    # Generator Defaults — XOR
+    "XOR_N_POINTS_DEFAULT",
+    "XOR_NOISE_DEFAULT",
+    "XOR_TRAIN_RATIO_DEFAULT",
+    "XOR_N_POINTS_MIN",
+    "XOR_NOISE_MIN",
+    "XOR_TRAIN_RATIO_MIN",
+    "XOR_TRAIN_RATIO_MAX",
+    "XOR_CORNERS",
+    "XOR_CORNER_LABELS",
+    "XOR_NUM_CORNERS",
+    "XOR_NUM_CLASSES",
+    # Generator Defaults — Circle
+    "CIRCLE_N_POINTS_DEFAULT",
+    "CIRCLE_NOISE_DEFAULT",
+    "CIRCLE_FACTOR_DEFAULT",
+    "CIRCLE_TRAIN_RATIO_DEFAULT",
+    "CIRCLE_N_POINTS_MIN",
+    "CIRCLE_NOISE_MIN",
+    "CIRCLE_FACTOR_MIN",
+    "CIRCLE_FACTOR_MAX",
+    "CIRCLE_TRAIN_RATIO_MIN",
+    "CIRCLE_TRAIN_RATIO_MAX",
+    "CIRCLE_NUM_CLASSES",
+    # Generator Defaults — Moon
+    "MOON_N_POINTS_DEFAULT",
+    "MOON_NOISE_DEFAULT",
+    "MOON_TRAIN_RATIO_DEFAULT",
+    "MOON_N_POINTS_MIN",
+    "MOON_NOISE_MIN",
+    "MOON_TRAIN_RATIO_MIN",
+    "MOON_TRAIN_RATIO_MAX",
+    "MOON_NUM_CLASSES",
+    "MOON_LOWER_X_OFFSET",
+    "MOON_LOWER_Y_OFFSET",
+    "MOON_LOWER_Y_SHIFT",
+    # Fake Service Identity
+    "FAKE_SERVICE_STATUS",
+    "FAKE_SERVICE_NAME",
+    "FAKE_SERVICE_VERSION",
+    "FAKE_SERVICE_UPTIME_SECONDS",
+    # NPZ Artifact Contract (WS-1 / juniper-data#168)
+    "NPZ_SPLITS",
+    "FAKE_VAL_RATIO_DEFAULT",
+    "NPZ_KEY_X",
+    "NPZ_KEY_Y",
+    "NPZ_KEY_Y_REG",
+    "NPZ_KEY_T",
+    "NPZ_KEY_DT",
+    "NPZ_KEY_TARGET_DT",
+    "NPZ_KEY_OBSERVED_MASK",
+    "NPZ_KEY_PADDING_MASK",
+    "NPZ_KEY_SEQ_LENGTHS",
+    "ContractKind",
+    "CONTRACT_KIND_TABULAR",
+    "CONTRACT_KIND_SEQUENCE",
+    "TASK_TYPE_CLASSIFICATION",
+    "TASK_TYPE_REGRESSION",
 ]
 
 # ─── Service Configuration ───────────────────────────────────────────────────
@@ -55,6 +193,13 @@ FAKE_BASE_URL: str = "http://fake-data:8100"
 DEFAULT_TIMEOUT: int = 30
 DEFAULT_RETRIES: int = 3
 DEFAULT_BACKOFF_FACTOR: float = 0.5
+# APD-ECO-002: urllib3 applies this as an ABSOLUTE additive term --
+# ``backoff_value += random.random() * backoff_jitter`` -- not a proportional
+# one. Without it every client that trips the same transient outage retries on
+# an identical schedule, so a service that is already failing is hit by a
+# synchronised herd. Matched to DEFAULT_BACKOFF_FACTOR so the spread is a full
+# window on the first retry, which is the step that carries the most callers.
+DEFAULT_BACKOFF_JITTER: float = 0.5
 RETRYABLE_STATUS_CODES: List[int] = [429, 500, 502, 503, 504]
 # XREPO-11 (2026-04-24): auto-retry is now restricted to idempotent
 # HTTP methods per RFC 9110 §9.2.2. POST, PATCH and DELETE were
@@ -148,6 +293,18 @@ GENERATOR_CHECKERBOARD: str = "checkerboard"
 GENERATOR_CSV_IMPORT: str = "csv_import"
 GENERATOR_MNIST: str = "mnist"
 GENERATOR_ARC_AGI: str = "arc_agi"
+# W-9 (CLI experimentation plan §11, 2026-08-08): added constants for the 7
+# server generators the client still lacked — the equities pair plus the five
+# sequence generators (juniper-data ≥ 0.8/0.9). The parity test now also
+# cross-checks the pinned mirror against the LIVE server registry whenever
+# juniper-data is importable, so this list can no longer drift silently.
+GENERATOR_EQUITIES: str = "equities"
+GENERATOR_EQUITIES_SEQ: str = "equities_seq"
+GENERATOR_MULTI_SINE: str = "multi_sine"
+GENERATOR_MACKEY_GLASS: str = "mackey_glass"
+GENERATOR_AR_P: str = "ar_p"
+GENERATOR_IRREGULAR_SINE: str = "irregular_sine"
+GENERATOR_DELAY_PRODUCT: str = "delay_product"
 
 # ─── Generator Catalog Metadata ──────────────────────────────────────────────
 
@@ -161,6 +318,13 @@ GENERATOR_DESCRIPTION_CHECKERBOARD: str = "Checkerboard pattern classification d
 GENERATOR_DESCRIPTION_CSV_IMPORT: str = "CSV/JSON import for custom datasets"
 GENERATOR_DESCRIPTION_MNIST: str = "MNIST and Fashion-MNIST digit classification dataset"
 GENERATOR_DESCRIPTION_ARC_AGI: str = "ARC-AGI visual reasoning tasks dataset"
+GENERATOR_DESCRIPTION_EQUITIES: str = "Real equities OHLCV tabular dataset (next-day direction)"
+GENERATOR_DESCRIPTION_EQUITIES_SEQ: str = "Real equities irregular-Δt sequence dataset (calendar-gap Δt)"
+GENERATOR_DESCRIPTION_MULTI_SINE: str = "Regular-Δt superimposed-sinusoid sequence dataset"
+GENERATOR_DESCRIPTION_MACKEY_GLASS: str = "Regular-Δt Mackey-Glass chaotic sequence dataset"
+GENERATOR_DESCRIPTION_AR_P: str = "Regular-Δt stable AR(p) linear-stochastic sequence dataset"
+GENERATOR_DESCRIPTION_IRREGULAR_SINE: str = "Irregular-Δt superimposed-sinusoid sequence dataset"
+GENERATOR_DESCRIPTION_DELAY_PRODUCT: str = "Irregular-Δt bilinear delay-product capacity sequence dataset"
 
 # ─── Generator Defaults — Spiral ─────────────────────────────────────────────
 
@@ -255,7 +419,27 @@ FAKE_SERVICE_UPTIME_SECONDS: float = 0.0
 
 # Split suffixes used for every per-split NPZ key (suffix a stem with
 # f"{stem}_{split}", e.g. f"{NPZ_KEY_X}_train").
-NPZ_SPLITS: Tuple[str, ...] = ("train", "test", "full")
+#
+# "val" is the in-loop validation partition of the three-way train/val/test
+# contract (design decision O-1). Membership here is presence-conditional --
+# validate_npz_contract skips any split a given artifact does not carry -- so
+# listing it does not require an artifact to provide it, and two-partition
+# legacy artifacts keep validating unchanged.
+#
+# "full" is GONE (decision 11, 2026-09-05). The *_full family is no longer part of
+# the contract: generators do not emit it and no consumer may require it.
+#
+# Removing it from this tuple does NOT stop a legacy artifact loading. Every stored
+# artifact still carries X_full, and validate_npz_contract skips any split it does
+# not list -- so an X_full that is present is simply not validated, which is what
+# "tolerate, do not require" means in practice. Adding it back to get it validated
+# would re-create the requirement this decision removed.
+NPZ_SPLITS: Tuple[str, ...] = ("train", "val", "test")
+
+# Validation share used by the synthetic generators in juniper_data_client.testing.
+# Applied alongside each generator's train ratio, so the default 0.8 / 0.1 carve
+# leaves the remainder to test.
+FAKE_VAL_RATIO_DEFAULT: float = 0.1
 
 # Canonical per-split key stems.
 NPZ_KEY_X: str = "X"  # features: (N, F) tabular or (W, L, F) sequence
@@ -268,9 +452,13 @@ NPZ_KEY_OBSERVED_MASK: str = "observed_mask"  # 1=real, 0=imputed (sequence)
 NPZ_KEY_PADDING_MASK: str = "padding_mask"  # 1=valid, 0=structural padding (sequence)
 NPZ_KEY_SEQ_LENGTHS: str = "seq_lengths"  # valid step count per window (sequence)
 
-# Contract discriminators returned by ``validate_npz_contract``.
-CONTRACT_KIND_TABULAR: str = "tabular"
-CONTRACT_KIND_SEQUENCE: str = "sequence"
+# Contract discriminators returned by ``validate_npz_contract``. The Literal
+# lets a caller exhaustively match on the result (APD-DCLIENT-006); annotating
+# the constants with Final[ContractKind] keeps their values and the Literal's
+# members from drifting apart -- a mismatch fails type checking.
+ContractKind = Literal["tabular", "sequence"]
+CONTRACT_KIND_TABULAR: Final[ContractKind] = "tabular"
+CONTRACT_KIND_SEQUENCE: Final[ContractKind] = "sequence"
 
 # ``task_type`` values carried in dataset metadata (meta.json, not the NPZ).
 TASK_TYPE_CLASSIFICATION: str = "classification"