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 and juniper-cascor-client, so consumers (notably juniper-canopy's recurrence backend adapter) drive every Juniper backend the same way.

Install

pip install juniper-recurrence-client          # once published
pip install -e ".[test]"                        # local development

Names and source layout. Unlike its two sibling clients, this package is published from the juniper-recurrence-client/ subdirectory of the pcalnon/juniper-recurrence monorepo — there is no standalone juniper-recurrence-client repository. Three names are in play and all three differ:

What	Value
Install (distribution name)	pip install juniper-recurrence-client
Import (module name)	import juniper_recurrence_client
Source (repository)	pcalnon/juniper-recurrence, path juniper-recurrence-client/

So if import juniper_recurrence_client raises ModuleNotFoundError, the distribution to install is juniper-recurrence-client; and issues or PRs for this client belong on the juniper-recurrence repository.

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).

Port: 8211 is the juniper-recurrence service's default host port; under Docker it maps to the container's 8210 (see the app README). Point the client at whichever host:port the service is published on.

Quick start

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 trainval pool (juniper-recurrence 0.8.0, whose response
# reports the embargo it used under "folding"; older services use the whole `full` view). Omit
# `embargo` to take the service's default, one look-back from 0.8.0.
result = client.crossval(name="equities", n_folds=4, scheme="expanding")
print(result["eval_aggregate"])

# Inspect
client.get_model()        # topology + metrics
client.training_status()  # state + events
client.is_ready()         # readiness probe

API surface

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.