sonnet-server 0.2.0

Domain-service foundation for Petrarca Labs backend services

Sonnet Server

Domain-service foundation for Petrarca backend services. Provides the infrastructure layer that every backend service inherits: FastAPI app factory, extension-based lifecycle, database connectivity, messaging, caching, DI, readiness pipeline, guards, CLI framework, and system endpoints.

What it provides

• Extension protocol -- opt-in subsystem lifecycle (database, messaging, cache, profiles). Infrastructure and profile extensions with conditional startup and router mounting.
• Database -- engine management, ambient sessions, CRUD repository, Alembic utilities, advisory locks.
• Messaging -- content-based router with pluggable channels (Postgres LISTEN/NOTIFY, NATS, in-process), CloudEvents envelope, @handles decorator.
• Cache -- managed cache with pluggable backends (local, distributed, near-cache), cross-process invalidation via messaging.
• Readiness pipeline -- composable health check stages with decorator-based auto-discovery.
• Guards -- protocol-based authentication and tenant context validation.
• DI -- type-keyed service registry with factory and singleton patterns.
• CLI -- Typer-based framework with reusable db check / db upgrade commands.
• System endpoints -- /ping, /version, /health-check, plus extension-contributed routes (/messaging, /cache).

Prerequisites

• Python 3.14+
• Task (task runner)
• uv (Python package manager)

Setup

Situation	Command
Fresh clone	task install
After git pull (no dep changes)	task sync
After editing pyproject.toml	task install
Upgrade deps to latest	task upgrade → commit uv.lock

This package is part of the sonnet-server workspace. See the workspace root for setup instructions.

Development

From the package directory (packages/sonnet-server/):

task fct            # format, check, test
task test           # tests only
task test:unit      # unit tests only

Or from the workspace root:

task fct            # all packages

Consumer usage

Dependency

Add to your project's pyproject.toml:

[project]
dependencies = [
    "sonnet-server[all]>=0.1.8",
]

For local co-development, add an editable source override:

[tool.uv.sources]
sonnet-server = { path = "../sonnet-server/packages/sonnet-server", editable = true }

Settings

Subclass Settings with your own env prefix. Call init_settings() at the bottom of your settings module to register with sonnet-server:

# my_app/settings.py
from functools import lru_cache
from pydantic_settings import SettingsConfigDict
from sonnet_server.settings import Settings as SonnetSettings, init_settings

class Settings(SonnetSettings):
    model_config = SettingsConfigDict(env_prefix="MY_APP_", ...)
    # project-specific fields here

@lru_cache
def get_settings() -> Settings:
    return Settings()

init_settings(get_settings())

All sonnet-server infrastructure (database, messaging, cache, checks) will then read from MY_APP_* env vars.

License

Apache License 2.0. See LICENSE.md.