juniper-cascor

A Cascade-Correlation neural-network training service with live REST + WebSocket streaming.

juniper-cascor is a FastAPI service that implements the Fahlman & Lebiere (1990) Cascade-Correlation algorithm — a constructive network that grows itself by recruiting hidden units one at a time, each chosen to maximise correlation with the network's remaining error. Instead of fixing the architecture up front, CasCor builds it as training proceeds.

The service exposes a REST API for network and training control and live WebSocket streams for real-time introspection of the growing network. It trains on datasets from juniper-data, is driven over HTTP by juniper-cascor-client, monitored live by juniper-canopy, and can offload candidate-unit training to distributed juniper-cascor-worker instances.

Part of the Juniper platform. juniper-cascor is the Cascade-Correlation training backend of Juniper — a multi-package ML research platform built around constructive and recurrent neural networks.

Install

pip install juniper-cascor

For development from a clone:

git clone https://github.com/pcalnon/juniper-cascor.git && cd juniper-cascor
pip install -e ".[ml,api,observability]"

Run

python src/server.py                          # binds 127.0.0.1:8200
curl http://localhost:8200/v1/health/ready

A minimal train loop over the REST API — create a network, stage a dataset, start training:

curl -sX POST localhost:8200/v1/network \
  -H 'Content-Type: application/json' -d '{"config": {"input_size": 2, "output_size": 2}}'
curl -sX POST localhost:8200/v1/training/dataset \
  -H 'Content-Type: application/json' -d '{"dataset": {"generator": "spiral"}}'
curl -sX POST localhost:8200/v1/training/start \
  -H 'Content-Type: application/json' -d '{"params": {"max_epochs": 100}}'
curl -s localhost:8200/v1/training/status

API

REST routes (prefix /v1; responses wrapped in a {status, data, meta} envelope):

WebSocket streams: /ws/training (live metrics + topology, resumable), /ws/control (control + heartbeat), /ws/v1/workers (the distributed worker pool). WebSocket admission is capped globally across all three sockets, with an additional per-identity cap on /ws/control; over-cap clients are closed with code 1013.

Configuration

Settings load from the JUNIPER_CASCOR_ environment namespace. Common knobs (full surface in docs/install/REFERENCE.md):

Docker

docker build -t juniper-cascor:latest .
docker run --rm -p 127.0.0.1:8200:8200 \
  -e JUNIPER_CASCOR_HOST=0.0.0.0 \
  -e JUNIPER_CASCOR_LOOPBACK_PUBLISH_ATTESTED=true \
  -e JUNIPER_CASCOR_API_KEYS=replace-with-a-strong-key \
  -e JUNIPER_DATA_URL=http://host.docker.internal:8100 \
  juniper-cascor:latest

The host-side publish is loopback-only; JUNIPER_CASCOR_LOOPBACK_PUBLISH_ATTESTED=true attests that boundary so the startup bind guard allows the container's internal 0.0.0.0 bind. (Behind a fronting authenticating reverse proxy instead, attest JUNIPER_CASCOR_AUTH_PROXY_ATTESTED=true.) Health is probed at /v1/health/ready. For the full stack, see juniper-deploy.

Status

Live on PyPI. The current version is shown by the badge above; see CHANGELOG.md. It trains on datasets from juniper-data (JUNIPER_DATA_URL) and is driven by juniper-cascor-client.

Documentation

• docs/install/QUICK_START.md — installation and setup
• docs/install/USER_MANUAL.md — comprehensive usage guide
• docs/api/API_REFERENCE.md — REST + WebSocket API reference
• docs/install/REFERENCE.md — configuration reference

License

MIT — see LICENSE.