juniper-recurrence 0.1.0__tar.gz

juniper_recurrence-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: juniper-recurrence
+Version: 0.1.0
+Summary: FastAPI + CLI service wrapping the Δt-native LMU recurrence model on the juniper-service-core framework
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Repository, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Issues, https://github.com/pcalnon/juniper-recurrence/issues
+Keywords: juniper,recurrence,lmu,fastapi,time-series,irregular-dt,model-service
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: juniper-service-core<0.2.0,>=0.1.0
+Requires-Dist: juniper-model-core<0.2.0,>=0.1.0
+Requires-Dist: juniper-recurrence-model<0.2.0,>=0.1.0
+Requires-Dist: juniper-data-client<0.5.0,>=0.4.1
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Provides-Extra: observability
+Requires-Dist: juniper-observability>=0.3.1; extra == "observability"
+
+# juniper-recurrence
+
+**Project**: Juniper — Cascade Correlation Neural Network Research Platform
+**Application**: juniper-recurrence (FastAPI + CLI service)
+**Author**: Paul Calnon
+**License**: MIT License
+**Version**: 0.1.0
+
+FastAPI + CLI service that wraps the Δt-native Legendre Memory Unit regressor
+([`juniper-recurrence-model`](https://github.com/pcalnon/juniper-recurrence)) on the
+shared [`juniper-service-core`](https://pypi.org/project/juniper-service-core/)
+framework. It loads 3-D windowed sequences (`equities_seq`, the WS-1 irregular-Δt
+contract) through [`juniper-data-client`](https://pypi.org/project/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
+
+```bash
+pip install juniper-recurrence
+```
+
+All upstreams resolve from PyPI: `juniper-service-core`, `juniper-model-core`,
+`juniper-recurrence-model`, `juniper-data-client`, plus `fastapi` / `uvicorn`.
+
+## Run
+
+```bash
+# 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):
+
+| Route | Method | Behavior |
+|---|---|---|
+| `/v1/health`, `/v1/health/ready` | GET | Liveness / readiness (exempt). |
+| `/v1/train` | POST | Train the LMU on a dataset (synchronous); returns the `TrainResult`. |
+| `/v1/training/status` | GET | `idle` / `trained` + last metrics + training events. |
+| `/v1/predict` | POST | Continuous predictions for inline `X` (+ `dt`) or a dataset ref. |
+| `/v1/model` | GET | Current model topology + regression metrics. |
+| `/v1/dataset` | GET | Descriptor of the trained-on dataset. |
+| `/docs` | GET | OpenAPI / Swagger UI (exempt). |
+
+Training runs **inline** (a one-shot closed-form solve), so `POST /v1/train` returns the
+result in the response — no background jobs or WebSocket streams in v1.
+
+```bash
+# 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)
+
+```bash
+# 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).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `JUNIPER_RECURRENCE_HOST` | `0.0.0.0` | Bind host (container default; `127.0.0.1` locally). |
+| `JUNIPER_RECURRENCE_PORT` | `8210` | Bind port (deploy maps host `8211` → container `8210`). |
+| `JUNIPER_RECURRENCE_API_KEYS` | _(unset)_ | CSV or JSON-array of valid `X-API-Key` values. |
+| `JUNIPER_DATA_URL` | `http://localhost:8100` | Upstream juniper-data base URL. |
+| `JUNIPER_DATA_API_KEY` | _(unset)_ | Outbound `X-API-Key` to juniper-data. |
+
+## Development
+
+```bash
+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.
+
+```bash
+git tag juniper-recurrence-v0.1.0
+git push origin juniper-recurrence-v0.1.0
+```
+
+## Ecosystem
+
+Part of the [Juniper](https://github.com/pcalnon) 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.

juniper_recurrence-0.1.0/README.md

@@ -0,0 +1,110 @@
+# juniper-recurrence
+
+**Project**: Juniper — Cascade Correlation Neural Network Research Platform
+**Application**: juniper-recurrence (FastAPI + CLI service)
+**Author**: Paul Calnon
+**License**: MIT License
+**Version**: 0.1.0
+
+FastAPI + CLI service that wraps the Δt-native Legendre Memory Unit regressor
+([`juniper-recurrence-model`](https://github.com/pcalnon/juniper-recurrence)) on the
+shared [`juniper-service-core`](https://pypi.org/project/juniper-service-core/)
+framework. It loads 3-D windowed sequences (`equities_seq`, the WS-1 irregular-Δt
+contract) through [`juniper-data-client`](https://pypi.org/project/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
+
+```bash
+pip install juniper-recurrence
+```
+
+All upstreams resolve from PyPI: `juniper-service-core`, `juniper-model-core`,
+`juniper-recurrence-model`, `juniper-data-client`, plus `fastapi` / `uvicorn`.
+
+## Run
+
+```bash
+# 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):
+
+| Route | Method | Behavior |
+|---|---|---|
+| `/v1/health`, `/v1/health/ready` | GET | Liveness / readiness (exempt). |
+| `/v1/train` | POST | Train the LMU on a dataset (synchronous); returns the `TrainResult`. |
+| `/v1/training/status` | GET | `idle` / `trained` + last metrics + training events. |
+| `/v1/predict` | POST | Continuous predictions for inline `X` (+ `dt`) or a dataset ref. |
+| `/v1/model` | GET | Current model topology + regression metrics. |
+| `/v1/dataset` | GET | Descriptor of the trained-on dataset. |
+| `/docs` | GET | OpenAPI / Swagger UI (exempt). |
+
+Training runs **inline** (a one-shot closed-form solve), so `POST /v1/train` returns the
+result in the response — no background jobs or WebSocket streams in v1.
+
+```bash
+# 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)
+
+```bash
+# 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).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `JUNIPER_RECURRENCE_HOST` | `0.0.0.0` | Bind host (container default; `127.0.0.1` locally). |
+| `JUNIPER_RECURRENCE_PORT` | `8210` | Bind port (deploy maps host `8211` → container `8210`). |
+| `JUNIPER_RECURRENCE_API_KEYS` | _(unset)_ | CSV or JSON-array of valid `X-API-Key` values. |
+| `JUNIPER_DATA_URL` | `http://localhost:8100` | Upstream juniper-data base URL. |
+| `JUNIPER_DATA_API_KEY` | _(unset)_ | Outbound `X-API-Key` to juniper-data. |
+
+## Development
+
+```bash
+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.
+
+```bash
+git tag juniper-recurrence-v0.1.0
+git push origin juniper-recurrence-v0.1.0
+```
+
+## Ecosystem
+
+Part of the [Juniper](https://github.com/pcalnon) 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.

juniper_recurrence-0.1.0/juniper_recurrence/__init__.py

@@ -0,0 +1,21 @@
+"""juniper-recurrence — FastAPI + CLI service for the Δt-native LMU recurrence model.
+
+The application layer (WS-4b) that wraps the already-shipped ``LMURegressor``
+(``juniper-recurrence-model``, WS-4a) on the ``juniper-service-core`` framework
+(WS-2), fed 3-D windowed sequences (``equities_seq``) via ``juniper-data-client``
+(WS-1). It is the first real consumer of service-core's ``create_app`` +
+``TrainingLifecycle`` (the 2nd-implementer proof for the *service* contract).
+
+Only :data:`__version__` is exposed at the top level, kept dependency-free so the
+package version is importable without pulling fastapi / pydantic-settings. The
+FastAPI app and its factory live in :mod:`juniper_recurrence.app`
+(``from juniper_recurrence.app import app, build_app``); the CLI entrypoint is
+:func:`juniper_recurrence.main.main`.
+
+Design of record: ``notes/JUNIPER_RECURRENCE_WS4B_APP_BUILD_PLAN_2026-06-15.md`` and
+``notes/JUNIPER_RECURRENCE_MODEL_DETAILED_DESIGN_2026-06-14.md`` (juniper-ml).
+"""
+
+from juniper_recurrence._version import __version__
+
+__all__ = ["__version__"]

juniper_recurrence-0.1.0/juniper_recurrence/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for the juniper-recurrence application version.
+
+Kept import-free so setuptools can parse ``__version__`` statically at build time
+(``[tool.setuptools.dynamic]`` in pyproject.toml) without importing fastapi /
+pydantic-settings. This also lets the TestPyPI publish-verify run a clean
+``import juniper_recurrence`` (top-level package re-exports only this value).
+"""
+
+__version__ = "0.1.0"

juniper_recurrence-0.1.0/juniper_recurrence/app.py

@@ -0,0 +1,83 @@
+"""FastAPI application assembly for the juniper-recurrence service.
+
+Builds on the *as-built* ``juniper-service-core`` app factory: ``create_app``
+mounts only the generic health router, so the owning service owns its
+security / middleware stack (the as-built reconciliation, plan §2). This module
+attaches that stack and exposes the module-level ``app`` that ``uvicorn`` (and the
+CLI ``serve`` subcommand) import.
+
+Middleware order mirrors the canonical cascor / canopy / data assembly —
+``RequestBodyLimitMiddleware`` → ``SecurityHeadersMiddleware`` →
+``SecurityMiddleware`` — added in that sequence so that, under Starlette's LIFO
+execution, ``SecurityMiddleware`` (API-key auth + rate limiting) runs outermost.
+
+The train / predict / model / dataset routers are threaded through
+``create_app(routers=...)``; a fresh :class:`AppState` (the in-process model / result /
+event holder) is created per ``build_app`` and stashed on ``app.state`` for the routers.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from juniper_service_core import (
+    RequestBodyLimitMiddleware,
+    SecurityHeadersMiddleware,
+    SecurityMiddleware,
+    build_api_key_auth,
+    build_rate_limiter,
+    create_app,
+)
+
+from juniper_recurrence._version import __version__
+from juniper_recurrence.routers import dataset_router, model_router, predict_router, training_router
+from juniper_recurrence.settings import Settings
+from juniper_recurrence.state import AppState
+
+__all__ = ["build_app", "app"]
+
+
+def build_app(settings: Settings | None = None) -> FastAPI:
+    """Assemble the juniper-recurrence FastAPI app.
+
+    Args:
+        settings: Pre-built settings (tests inject these to exercise auth /
+            rate-limit configurations). Defaults to ``Settings()``, which reads
+            the ``JUNIPER_RECURRENCE_`` environment namespace.
+
+    Returns:
+        A configured :class:`~fastapi.FastAPI` instance with the generic health
+        router (from ``create_app``) plus the security / middleware stack.
+    """
+    settings = settings or Settings()
+
+    application = create_app(
+        title="Juniper Recurrence",
+        version=__version__,
+        routers=(training_router, predict_router, model_router, dataset_router),
+    )
+
+    # Middleware (Starlette LIFO: last added runs first on the request path). This
+    # exact order is the de-cascored canonical assembly shared by cascor / canopy /
+    # data: body-limit innermost, security-headers next, API-key auth + rate-limit
+    # outermost.
+    application.add_middleware(RequestBodyLimitMiddleware)
+    application.add_middleware(SecurityHeadersMiddleware)
+    api_key_auth = build_api_key_auth(settings.resolve_api_keys())
+    rate_limiter = build_rate_limiter(
+        requests_per_minute=settings.rate_limit_requests_per_minute,
+        enabled=settings.rate_limit_enabled,
+    )
+    application.add_middleware(SecurityMiddleware, api_key_auth=api_key_auth, rate_limiter=rate_limiter)
+
+    # Stash per-app instances for routers / tests (mirrors cascor's app.state usage).
+    # AppState is created fresh per build_app, so each app — and each test — gets
+    # isolated in-process model / result / event state.
+    application.state.settings = settings
+    application.state.api_key_auth = api_key_auth
+    application.state.app_state = AppState()
+
+    return application
+
+
+# Module-level ASGI app for ``uvicorn juniper_recurrence.app:app`` (CLI ``serve``).
+app = build_app()

juniper_recurrence-0.1.0/juniper_recurrence/data.py

@@ -0,0 +1,105 @@
+"""Data path: juniper-data-client → 3-D ``equities_seq`` NPZ → model kwargs (plan §8).
+
+Resolves a dataset reference to a ``dataset_id``, downloads the NPZ artifact, runs
+juniper-data-client's full-contract validator **when the installed client exposes it**
+(see the guarded import below), then maps it to the arrays ``LMURegressor`` consumes via
+the model package's ``sequence_data_from_arrays`` (reusing the canonical WS-1 key layout
++ ``dt`` rules instead of re-deriving them — also the validation floor when the validator
+is absent).
+
+Framework-light by design: takes primitives (no FastAPI / pydantic / settings import),
+so the routers and the headless CLI ``train`` share it. ``JuniperDataClient`` and
+``validate_npz_contract`` are imported at module level so tests can monkeypatch them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from juniper_data_client import JuniperDataClient
+from juniper_recurrence_model import SequenceData, sequence_data_from_arrays
+
+try:
+    # ``validate_npz_contract`` landed in juniper-data-client AFTER the published 0.4.1
+    # pin. When the installed client provides it, it runs as the authoritative
+    # full-contract gate; otherwise the model-side ``sequence_data_from_arrays`` checks
+    # (X is 3-D, the dt rules, a regression target present) are the validation floor.
+    # Bump the ``juniper-data-client`` pin once the validator publishes to make it hard.
+    from juniper_data_client import validate_npz_contract
+except ImportError:  # pragma: no cover - depends on the installed juniper-data-client version
+    validate_npz_contract = None
+
+__all__ = ["load_sequence_data"]
+
+
+def _resolve_dataset_id(
+    client: JuniperDataClient,
+    *,
+    dataset_id: str | None,
+    name: str | None,
+    generator: str | None,
+    params: dict[str, Any] | None,
+) -> str:
+    """Resolve a dataset reference to a concrete ``dataset_id``.
+
+    Precedence: explicit ``dataset_id`` → latest version of ``name`` → create a new
+    dataset from ``generator`` + ``params``.
+    """
+    if dataset_id:
+        return dataset_id
+    if name:
+        latest = client.get_latest(name)
+        resolved = latest.get("dataset_id")
+        if not resolved:
+            raise ValueError(f"no dataset_id in latest version of {name!r}")
+        return resolved
+    if generator:
+        created = client.create_dataset(generator=generator, params=dict(params or {}), persist=True)
+        resolved = created.get("dataset_id")
+        if not resolved:
+            raise ValueError(f"no dataset_id returned creating {generator!r} dataset")
+        return resolved
+    raise ValueError("dataset ref requires one of: dataset_id, name, generator")
+
+
+def load_sequence_data(
+    *,
+    base_url: str,
+    api_key: str | None = None,
+    dataset_id: str | None = None,
+    name: str | None = None,
+    generator: str | None = None,
+    params: dict[str, Any] | None = None,
+    split: str = "train",
+) -> tuple[SequenceData, dict[str, Any]]:
+    """Fetch and map one split of a 3-D sequence dataset for the LMU regressor.
+
+    Returns the :class:`SequenceData` (``X`` / ``y`` / ``dt`` / ``target_dt`` /
+    ``seq_lengths``) plus a plain descriptor dict for ``DatasetDescriptor``.
+
+    Raises:
+        juniper_data_client.JuniperDataClientError: on upstream fetch failures.
+        ValueError: when the artifact violates the contract or is not a 3-D sequence.
+    """
+    client = JuniperDataClient(base_url=base_url, api_key=api_key)
+    try:
+        resolved_id = _resolve_dataset_id(client, dataset_id=dataset_id, name=name, generator=generator, params=params)
+        arrays = client.download_artifact_npz(resolved_id)
+        if validate_npz_contract is not None:
+            validate_npz_contract(arrays)  # full-contract gate when the client provides it (raises ValueError)
+        sequence = sequence_data_from_arrays(arrays, split)
+    finally:
+        client.close()
+
+    descriptor = {
+        "dataset_id": resolved_id,
+        "name": name,
+        "split": split,
+        "n_windows": int(sequence.X.shape[0]),
+        "lookback": int(sequence.X.shape[1]),
+        "n_features": int(sequence.X.shape[2]),
+        "output_dim": int(sequence.y.shape[1]) if sequence.y.ndim > 1 else 1,
+        "has_target_dt": sequence.target_dt is not None,
+        "has_seq_lengths": sequence.seq_lengths is not None,
+    }
+    return sequence, descriptor

juniper_recurrence-0.1.0/juniper_recurrence/events.py

@@ -0,0 +1,34 @@
+"""In-memory training-event sink for the juniper-recurrence app (plan §9).
+
+A bounded, ordered ring buffer that is itself the ``on_event`` callable passed to
+``juniper_service_core.TrainingLifecycle``. The lifecycle stamps a monotonic ``seq``
+on each event before it arrives here, so a snapshot is already legally ordered. The
+buffer feeds ``GET /v1/training/status``; older events past ``maxlen`` are dropped
+(a single synchronous run emits only ``training_start`` → ``epoch_end`` →
+``training_end``, so the default cap is never reached in practice).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from juniper_model_core import TrainingEvent
+
+__all__ = ["EventSink"]
+
+
+class EventSink:
+    """A bounded, ordered sink for :class:`~juniper_model_core.TrainingEvent`\\ s."""
+
+    def __init__(self, maxlen: int = 256) -> None:
+        self._events: deque[TrainingEvent] = deque(maxlen=maxlen)
+
+    def __call__(self, event: TrainingEvent) -> None:
+        """Append an emitted event (the ``on_event`` lifecycle hook)."""
+        self._events.append(event)
+
+    def snapshot(self) -> list[TrainingEvent]:
+        """An ordered copy of the buffered events (oldest first)."""
+        return list(self._events)

juniper_recurrence-0.1.0/juniper_recurrence/main.py

@@ -0,0 +1,116 @@
+"""CLI entrypoint for the juniper-recurrence service (C2 dual-mode).
+
+* ``juniper-recurrence serve`` launches the FastAPI app under uvicorn (single
+  worker; in-process state).
+* ``juniper-recurrence train`` is headless: load a 3-D NPZ via the shared data
+  adapter, fit ``LMURegressor``, print the regression metrics, and optionally persist
+  the model via ``LMUSerializer``. It reuses the exact ``data.load_sequence_data`` +
+  model construction the ``/v1/train`` route uses.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from juniper_recurrence._version import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the ``juniper-recurrence`` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="juniper-recurrence",
+        description="FastAPI + CLI service for the Δt-native LMU recurrence model.",
+    )
+    parser.add_argument("--version", action="version", version=f"juniper-recurrence {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True, metavar="{serve,train}")
+
+    serve = subparsers.add_parser("serve", help="Run the FastAPI service under uvicorn.")
+    serve.add_argument("--host", default=None, help="Bind host (defaults to JUNIPER_RECURRENCE_HOST / settings).")
+    serve.add_argument("--port", type=int, default=None, help="Bind port (defaults to JUNIPER_RECURRENCE_PORT / settings).")
+
+    train = subparsers.add_parser("train", help="Headless: fit the LMU on a dataset and print metrics.")
+    train.add_argument("--dataset", default=None, help="Dataset id to train on.")
+    train.add_argument("--name", default=None, help="Dataset name (uses the latest version).")
+    train.add_argument("--generator", default=None, help="Generator to create a dataset from (e.g. equities_seq).")
+    train.add_argument("--split", default="train", help="Split to train on (train/test/full; default: train).")
+    train.add_argument("--d", type=int, default=None, help="LMU memory order (default: settings.default_d).")
+    train.add_argument("--theta", type=float, default=None, help="LMU window length θ (default: data-driven).")
+    train.add_argument("--ridge", type=float, default=None, help="Readout L2 penalty (default: settings.default_ridge).")
+    train.add_argument("--out", default=None, help="Path to save the trained model (.npz) via LMUSerializer.")
+
+    return parser
+
+
+def _serve(args: argparse.Namespace) -> int:
+    """Run ``uvicorn`` against the module-level app, honoring host/port overrides."""
+    import uvicorn
+
+    from juniper_recurrence.settings import Settings
+
+    settings = Settings()
+    host = args.host or settings.host
+    port = args.port or settings.port
+    # Import string (not the app object) so uvicorn owns process/worker lifecycle.
+    uvicorn.run("juniper_recurrence.app:app", host=host, port=port)
+    return 0
+
+
+def _train(args: argparse.Namespace) -> int:
+    """Headless train: load a 3-D NPZ, fit ``LMURegressor``, print metrics, persist."""
+    from juniper_recurrence_model import LMURegressor, LMUSerializer
+
+    from juniper_recurrence.data import load_sequence_data
+    from juniper_recurrence.settings import Settings
+
+    if not (args.dataset or args.name or args.generator):
+        print("error: train requires one of --dataset / --name / --generator", file=sys.stderr)
+        return 2
+
+    settings = Settings()
+    sequence, descriptor = load_sequence_data(
+        base_url=settings.juniper_data_url,
+        api_key=settings.juniper_data_api_key,
+        dataset_id=args.dataset,
+        name=args.name,
+        generator=args.generator,
+        split=args.split,
+    )
+
+    d = args.d if args.d is not None else settings.default_d
+    theta = args.theta if args.theta is not None else settings.default_theta
+    ridge = args.ridge if args.ridge is not None else settings.default_ridge
+
+    model = LMURegressor(d=d, theta=theta, ridge=ridge)
+    result = model.fit(sequence.X, sequence.y, **sequence.fit_kwargs())
+
+    print(f"Trained LMURegressor on dataset {descriptor['dataset_id']} (split={descriptor['split']}, windows={descriptor['n_windows']}, F={descriptor['n_features']}).")
+    print("Metrics:")
+    for key, value in result.final_metrics.items():
+        print(f"  {key}: {value:.6f}")
+
+    if args.out:
+        LMUSerializer().save(model, args.out)
+        print(f"Saved model to {args.out}")
+
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI dispatch entrypoint (``[project.scripts] juniper-recurrence``)."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        return _serve(args)
+    if args.command == "train":
+        return _train(args)
+
+    # ``required=True`` on the subparser makes this unreachable; kept as a guard.
+    parser.error(f"unknown command: {args.command!r}")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

juniper_recurrence-0.1.0/juniper_recurrence/routers/__init__.py

@@ -0,0 +1,13 @@
+"""API routers for the juniper-recurrence service (plan §6).
+
+Each router is mounted by :func:`juniper_recurrence.app.build_app` via
+``create_app(routers=...)``. All routes are regression-generic (RK-6) and protected by
+the app's ``SecurityMiddleware`` (health / docs stay exempt) — no per-route auth needed.
+"""
+
+from juniper_recurrence.routers.dataset import router as dataset_router
+from juniper_recurrence.routers.model import router as model_router
+from juniper_recurrence.routers.predict import router as predict_router
+from juniper_recurrence.routers.training import router as training_router
+
+__all__ = ["training_router", "predict_router", "model_router", "dataset_router"]