scalo

There's plenty of sage advice about running services in production at scale -- config cascades, structured logging with PII masking and secrets filtering, multi-backend secrets management, Prometheus, OpenTelemetry, backpressure, graceful shutdown -- but almost none of it as code you can just install and use.

This is that code.

Opinionated, drop-in, working out of the box. The patterns from the blog posts as an actual library -- not a framework you assemble from twenty packages and a weekend.

Same batteries, idiomatic in each language: pip install scalo (scalo-py) / cargo add scalo (scalo-rs). Built as the foundation for HyperI's production services; generic enough that you don't need to be at HyperI to use it.

What this is (and isn't) for

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

Not for: the hot path. If you're processing millions of messages per second and shaving microseconds matters, that code belongs in Rust -- see scalo-rs. scalo-py is "fast enough for control plane and integration"; scalo-rs is "fast enough for the hot path".

We optimise scalo-py sensibly -- no gratuitously slow choices, no obvious algorithmic mistakes -- but the lean is toward stability, expressiveness, and integration rather than microseconds. Readable abstractions beat inlined ones; clean composition beats hand-rolled loops; heavier deps are acceptable when they earn their keep. This design decision is why scalo-py allows substantial dependency trees and doesn't agonise over async dispatch overhead. We don't hard-iterate the hot path the way scalo-rs does, because that's scalo-rs's job.

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

What you get

Core modules — always installed (uv add scalo):

Optional modules — install via extras:

Installation

# Core only (logger, config, runtime, cli, version-check)
uv add scalo

# With common extras
uv add "scalo[http,metrics,kafka]"

# Full stack
uv add "scalo[http,metrics,expression,kafka,opentelemetry,secrets,deployment]"

Package naming: scalo on PyPI, scalo for Python imports.

Optional Extras Sizes

Quick Start

Logging

from scalo.logger import logger

logger.info("Service starting", version="1.0.0")
logger.error("DB connection failed", host="postgres", retry=3)

Auto-detects console vs container — structured JSON in containers, human-readable locally. Sensitive fields (passwords, tokens, API keys, etc.) are masked automatically.

Configuration

from scalo.config import settings

# Cascade: CLI args → ENV → .env → settings.yaml → defaults
host = settings.database.host
port = settings.api.port

ENV key mapping: settings.database.host → MYAPP_DATABASE_HOST (prefix is configurable per app).

Runtime Paths (container-aware)

from scalo import get_runtime_paths

runtime = get_runtime_paths()
config = runtime.config_dir / "app.yaml"   # /config in K8s, ~/.config locally
data   = runtime.data_dir  / "state.db"    # /data in K8s, ~/.local/share locally

Metrics

from scalo import create_metrics

metrics = create_metrics(namespace="myapp")
metrics.http_requests.inc()
metrics.active_users.set(42)
metrics.request_duration.observe(0.123)

Automatic process and container metrics (CPU, memory, FDs, uptime) come for free — no extra wiring.

Kafka

from scalo.kafka import KafkaClient, KafkaConsumer, KafkaProducer

Uses confluent-kafka-python (librdkafka) under the hood. Schema-registry integration, health checks, and admin operations included.

Secrets (multi-backend)

from scalo.secrets import SecretsManager

# Picks the configured backend: file, OpenBao/Vault, AWS, GCP, Azure
manager = SecretsManager.from_config()
api_key = await manager.get("stripe/api_key")

Two-tier caching (memory + disk), stale-cache fallback for backend outages.

CLI Framework (ServiceApp)

Subclass ServiceApp to get a standard service-CLI lifecycle (run, version, config-check) with no boilerplate. Config flows through the 7-layer cascade automatically.

from scalo.cli import ServiceApp, VersionInfo

class MyService(ServiceApp):
    name = "my-service"
    env_prefix = "MY_SVC"

    def version_info(self) -> VersionInfo:
        return VersionInfo(self.name, "1.0.0")

    async def run_service_async(self, config) -> None:
        # your service code
        ...

if __name__ == "__main__":
    MyService().cli()

DfeApp remains as a deprecated alias for ServiceApp to ease migration from hyperi-pylib; prefer ServiceApp in new code.

Health Check Endpoints — The Probe Trinity

For services deployed to Kubernetes, scalo's HTTP server provides the three K8s probe types:

Liveness MUST NEVER check downstream dependencies (a DB outage shouldn't restart your replicas). Readiness checks dependencies AND requires an explicit set_ready() call — cleared during graceful shutdown.

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.