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

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.