juniper-service-core

The shared FastAPI service-tier framework every Juniper model service is built on.

Standing up a model as a service means writing the same plumbing every time: an app factory, settings, health probes, API-key auth, Docker-secret loading, security middleware, a training lifecycle with status tracking and event streaming, the HTTP routes that drive it, live WebSocket streams, and — for distributed training — a worker pool. juniper-service-core is that plumbing, factored out of juniper-cascor into one model-agnostic package. You bring the model; it brings the service.

The -core suffix marks it as genuinely shared: it carries no model, training, or domain logic — those stay in the owning service and are injected. A new Juniper model service (regression, classification, whatever the model does) wires its model into the lifecycle and gets a consistent HTTP + WebSocket surface for free.

Dependency-free top-level import

import juniper_service_core pulls in no third-party runtime dependency — only __version__ loads eagerly. The rest of the public surface (create_app, SettingsBase, and the security / secrets / middleware / lifecycle / routes / websocket / worker helpers) resolves lazily on attribute access (PEP 562 __getattr__), so fastapi / pydantic-settings / starlette / numpy load only when you touch a name that needs them. That's what lets a --no-deps publish-verify import the package cleanly.

Install

pip install juniper-service-core

What's in the box

Import cost tracks the subsystem: .security, .secrets, .middleware, .launcher, and .workers are stdlib-/lightweight; .lifecycle needs juniper-model-core; .routes and .websocket need fastapi.

Quick start

A minimal, health-only service:

from juniper_service_core import create_app, SettingsBase
from pydantic_settings import SettingsConfigDict


class MyServiceSettings(SettingsBase):
    model_config = SettingsConfigDict(env_prefix="JUNIPER_MYSVC_")


app = create_app(title="My Service", version="1.0.0")
# GET /v1/health       -> {"status": "ok"}
# GET /v1/health/ready -> {"status": "ready"}

To serve a model, wrap it in a ServiceLifecycleManager, mount the generic routers, and expose the lifecycle on app.state — the routes read it from there:

from juniper_service_core import create_app, ServiceLifecycleManager, build_routers

manager = ServiceLifecycleManager(MyModel())   # MyModel = any juniper-model-core TrainableModel
app = create_app(title="My Model Service", version="1.0.0", routers=build_routers())
app.state.lifecycle = manager
# -> POST /v1/train, GET /v1/training/status, and the metrics / dataset / network / snapshot
#    routes, all driving your model. (Routes return 503 until app.state.lifecycle is wired.)

juniper-recurrence is the canonical worked example — its FastAPI service is essentially this wiring around an LMU regressor.

Who uses it

• juniper-recurrence — the first real consumer; its service is create_app + a lifecycle around the LMU regressor.
• juniper-cascor — the framework was extracted from cascor's service tier; cascor's own cutover onto it is in progress.

Any new Juniper model service should build on this rather than re-implementing the plumbing.

Status

Live on PyPI (Beta). The current version is shown by the badge above; see CHANGELOG.md for history. Pin with juniper-service-core>=0.2,<0.3.

Development

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

Design

Part of the Juniper ML research platform. The architecture and the cascor extraction plan are the model/middleware refactor design of record (notes/JUNIPER_2026-05-31_JUNIPER-ECOSYSTEM_MODEL-MIDDLEWARE-REFACTOR-DESIGN-AND-PLAN.md in juniper-ml).

License

MIT — see LICENSE.