scalo

Package
Meta

An integrated runtime for control-plane services. Attach and 'enterprise-up' your application.

Key features

• configuration cascade for local test through at scale k8s deployments (env, config, cli)
• automatically configured and integrated logger (line and json) for enterprise deployments
• auto enabled Otel and Prometheus metrics in expected forms and buckets for cloud and k8s deployments
• secrets management integration
• authentication and secrets integration for most common deployments and services
• deployment contracts, your code automatically generates docker, and k8s artefacts for deployment consumption

Install

uv add scalo                                    # core
uv add "scalo[http,metrics,kafka]"              # common extras
uv add "scalo[http,metrics,expression,kafka,opentelemetry,secrets,deployment]"

scalo on PyPI, scalo for imports. Extras and their install sizes are in docs/EXTRAS-FLAGS.md -- secrets-aws alone is ~100 MB, so pick the backend you use rather than secrets.

What it is for

Control-plane APIs, UI backends, orchestrators, CLI tools, integration glue, batch workloads, configuration management.

Not the hot path. Processing millions of messages a second belongs in Rust -- scalo-rs is the sister library for that. scalo-py is fast enough for control plane and integration; scalo-rs is fast enough for the hot path. So scalo-py leans to stability, expressiveness and integration: readable abstractions over inlined ones, heavier deps where they earn their keep, no agonising over async dispatch overhead.

Same conventions, DIFFERENT API, separate repo. Never assume parity.

This module exists because of this -- but for the backend: https://www.youtube.com/watch?v=xE9W9Ghe4Jk

What is in the box

Core, always installed:

By extra: http (retry with jitter), metrics (Prometheus + process and container gauges), expression (CEL), kafka (produce, consume, schema inference), opentelemetry (OTLP traces and metrics), secrets (OpenBao/Vault, AWS, GCP, Azure), deployment (Dockerfile, Helm, Argo, compose generators).

Wired together already, which is the part you would otherwise build: config, logging and metrics are global singletons with no init dance; the cascade feeds the CLI so run, version and config-check work without you parsing an argument; the metrics and health wiring feeds the Kubernetes probes; the deployment contract writes your chart, Dockerfile and Argo manifests from the config the app already declares.

Documentation

docs/README.md is the index. The ones you want first:

Two things worth reading before you deploy: /livez and /readyz are the whole health surface and there are no aliases, and the observability port is separate from your application's on purpose -- exposing user traffic must never expose the operator surface. Both are in HEALTH.md.

Development

make quality   # lint, type-check, security audit
make test      # run test suite
make build     # build wheel

License

Apache-2.0. Third-party attributions are recorded in NOTICE.

Related

• scalo-rs -- sister library for Rust services. Same opinions, same patterns, native Rust performance for hot-path workloads.
• Migrating from hyperi-pylib -- scalo is the renamed, Apache-2.0 continuation of hyperi-pylib; this guide covers the mechanical changes.

Context

What this is

HyperI's shared Python library -- config cascade, logging, metrics, health, secrets, Kafka and the deployment-contract generators -- published as scalo on PyPI under Apache-2.0.

It is scalo-rs's SISTER, not its twin: same conventions, DIFFERENT API, separate repo. Never assume parity. The divergence is recorded rather than theoretical -- src/scalo/data/masking-patterns.yaml names the sensitive fields each side knows and the other does not, and the two match differently, so the corpus holds only cases inside the overlap.

Where things live

Commands that prove a change

make quality   # lint, type-check, security audit
make test      # the suite
make build     # the wheel

addopts deselects no markers, so make test runs integration and e2e as well, and on a developer box that is not green. This run was 9 failed, 2552 passed, 31 skipped in 7m01s -- 6 GCP secrets tests wanting gcloud auth application-default login, 2 CLI tests binding a fixed 0.0.0.0:9090, and one Dockerfile build. Read the per-job CI result, never a local summary. Coverage is gated in .hyperi-ci.yaml.

What tends to bite

Where this sits

Generated from dfe-infra/suite.yaml via dfe-stack suite. Nothing in the suite feeds this repo -- it declares no inbound edges.