juniper-recurrence

Project: Juniper — Cascade Correlation Neural Network Research Platform Application: juniper-recurrence (FastAPI + CLI service) Author: Paul Calnon License: MIT License Version: 0.2.0

FastAPI + CLI service that wraps the Δt-native Legendre Memory Unit regressor (juniper-recurrence-model) on the shared juniper-service-core framework. It loads 3-D windowed sequences (equities_seq, the WS-1 irregular-Δt contract) through juniper-data-client and trains / serves the LMU over HTTP.

This is the application layer (WS-4b): the first real consumer of service-core's create_app + TrainingLifecycle. The model, the data foundation, and the service framework ship separately; this package is the glue + the HTTP/CLI surface.

Install

pip install juniper-recurrence
pip install "juniper-recurrence[torch]"   # adds the torch MLP readout (DP-3 Rung 2b)

All upstreams resolve from PyPI: juniper-service-core, juniper-model-core, juniper-recurrence-model, juniper-data-client, plus fastapi / uvicorn.

Run

# Serve the API (single worker, in-process state). Binds 0.0.0.0:8210 by default;
# set JUNIPER_RECURRENCE_HOST=127.0.0.1 for local-only.
juniper-recurrence serve
juniper-recurrence serve --host 127.0.0.1 --port 8210

Once running, the API exposes (every /v1/* route below requires X-API-Key when API keys are configured; health + docs are always exempt):

Both POST /v1/train and POST /v1/crossval run inline (closed-form solves) and return their result in the response — no background jobs or WebSocket streams in v1. A second cross-validation run while one is in progress returns 409.

POST /v1/train's final_metrics are in-sample: they are scored on the split the fit was trained on (dataset.split), and the response says so with metrics_scope: "in_sample". They measure fit, not generalisation; the route reports no held-out metric.

Both responses carry a diagnostics block per fit -- once on POST /v1/train, once per fold on POST /v1/crossval -- with the hyperparameters the fit resolved: theta (the data-driven value a theta=None request became, per fold), ridge_mode / ridge_selected (the lambda ridge="gcv" selected), gamma (the median-heuristic RFF bandwidth), and the gcv_at_edge / null_model flags (booleans on a GCV-selected fit, which juniper-recurrence-model 0.5.0 reports; null means not determined, as on a fixed-ridge fit). The train CLI prints the same block under Readout:.

POST /v1/train and POST /v1/crossval accept a readout selector (DP-3): "linear" (default, closed-form least squares), "rff" (nonlinear random-Fourier-features readout, with rff_features / rff_gamma), or "mlp" (a torch MLP with the mlp_* knobs — needs the [torch] extra; returns 503 if torch is not installed). ridge accepts a float or "gcv" (closed-form generalized-cross-validation selection). A linear-readout request that omits ridge gets the service's default_ridge, "gcv" since 0.7.0 (plan W5.8 (B)): the penalty is GCV-selected on the train-fold-standardised memory block, so on a drifting input the fit abstains (lambda at the grid ceiling, null_model: true in diagnostics) rather than extrapolate as the former 0.0 min-norm default did. An explicit ridge: 0.0, or JUNIPER_RECURRENCE_DEFAULT_RIDGE=0.0 on the service, restores the old behaviour. See the juniper-recurrence-model README for the spectrum.

# Train on a juniper-data dataset, then inspect the model.
curl -sX POST localhost:8210/v1/train \
  -H 'Content-Type: application/json' \
  -d '{"dataset": {"dataset_id": "<id>"}, "d": 16}'
curl -s localhost:8210/v1/model

Train (headless CLI)

# Fit the LMU on a dataset and persist it — no server.
juniper-recurrence train --dataset <id> --d 16 --out model.npz
juniper-recurrence train --name equities_seq_v1 --split train

# Create the dataset from a generator with explicit generator params, then fit it.
juniper-recurrence train --generator equities_seq --params '{"symbols": ["AAPL"], "start_date": "2015-01-01", "end_date": "2022-01-01", "lookback": 64, "fundamentals_fill": "drop", "regression_target": "log_return"}'
juniper-recurrence train --generator equities_seq --params-file equities_seq.json

--params (a JSON object) and --params-file (a file holding one) carry the generator params that POST /v1/train takes as dataset.params. They are mutually exclusive and need --generator. Pass them explicitly for equities_seq: the generator's bare defaults are not a trainable configuration. Either flag without --generator, malformed JSON, or JSON that is not an object exits 2. The printed metrics are in-sample, as on the route.

One caller per service

A recurrence service is exclusively owned by one caller at a time: it has one process-wide train_lock, one in-memory model and one snapshot directory. Two callers sharing a listener -- canopy and a CLI experiment suite, say -- get each other's 409s and silently score each other's models.

• The operation id is how a caller proves whose model it is scoring. Each POST /v1/train mints an operation_id when it takes the lock and returns it; a restore mints its own, which the restored model then carries. Pass it as expect_operation_id to /v1/predict and POST /v1/model/snapshots: a model produced by any other operation is refused with a 409 that names both ids.
• Who holds it, and what happened. A refused POST /v1/train gets a 409 whose detail names the holder (operation_id, busy_since, requested_by). GET /v1/training/status reports training while a fit runs, then trained or failed (with failure), plus model_operation_id for the model /v1/predict scores. Send an X-Request-ID with your train request; it comes back as requested_by.
• A fit is not cancellable. A caller that times out leaves the fit running under the lock; poll the status for its outcome rather than retrying.
• Keep callers apart by port. The juniper-ml experiment launcher (util/experiment_stack.bash) starts a fresh service per run on ports 8260-8289, and that is what keeps a CLI suite and canopy apart. Canopy's service URL is outside that range (unset by default; Compose sets http://juniper-recurrence:8210, host port 8211; a native service listens on 8210), so canopy and a suite pointed at the same native or Compose listener recreate the collision, and neither side warns.

Configuration

All settings read the JUNIPER_RECURRENCE_ environment namespace (e.g. JUNIPER_RECURRENCE_PORT). Secrets honor the Docker _FILE indirection (JUNIPER_RECURRENCE_API_KEYS_FILE, JUNIPER_DATA_API_KEY_FILE). When no API keys are configured, authentication is disabled (open access — development default).

Development

pip install -e ".[test]"
pytest tests/ -v

Publishing

Releases are published to PyPI via GitHub Actions (.github/workflows/publish-recurrence-app.yml) on a juniper-recurrence-v* tag — TestPyPI first (with a --no-deps install verification), then PyPI, via OIDC trusted publishing (no API tokens). The model package (juniper-recurrence-model) publishes separately on juniper-recurrence-model-v* tags.

# Cut a GitHub Release on a juniper-recurrence-v* tag (the ecosystem convention — not a
# bare `git push <tag>`); the Release drives publish-recurrence-app.yml (TestPyPI → PyPI).
gh release create juniper-recurrence-v0.2.0 --generate-notes

Ecosystem

Part of the Juniper ML research platform. See the WS-4b build plan (notes/JUNIPER_RECURRENCE_WS4B_APP_BUILD_PLAN_2026-06-15.md in juniper-ml) for the design of record.