sonnet-core

The framework-agnostic foundation beneath the sonnet packages. Data access, models and logic that behave identically in an HTTP handler, a CLI command, a worker or a test.

Version 0.2.0. No FastAPI, no Starlette, no uvicorn, no Typer -- that is the point of the package.

What it provides

• Database -- pooled engines, the ambient session, transaction boundaries, Alembic helpers and advisory locks.
• CRUD repository -- CrudRepository and CrudConfig: list, get, create, update and delete derived from a SQLModel table, including versioned entities.
• Filtering -- a transport-neutral filter AST, declaration-driven validation, and compilation to SQLAlchemy.
• Readiness pipeline -- the staged check engine and its registries, usable outside a server.
• State machines -- declarative, serializable entity lifecycles with guards.
• Resource layer -- ResourceSpec, one resource declaration that both REST and CLI adapters consume.
• Service registry -- ServiceRegistry, type-keyed DI with singletons and factories.
• Models and ids -- dynamic model building, record-to-response conversion, PageResult, time-sortable ids, JSON Schema validation, version ordering.
• Exceptions -- the shared domain error vocabulary.

Install

uv add sonnet-core

Depends on pydantic, sqlmodel, sqlalchemy, alembic, tenacity, arrow, jsonschema and loguru. You supply the database driver; psycopg is the expected one. The only extra is dev.

Root re-export policy

Importing sonnet_core gives you the cheap things: ids, exceptions, model helpers, PageResult, ResourceSpec, ServiceRegistry. Three subpackages are deliberately not re-exported at the root, because importing them costs more than the always-on dependencies:

from sonnet_core.database import borrow_db_session
from sonnet_core.readiness_pipeline import readiness_check
from sonnet_core.utils.filtering import parse_query

A caller that wants only exceptions does not pay for engine setup.

Usage

A repository is a class with a configuration attribute; the query methods come from CrudRepository, and the session travels in a context variable rather than through every call.

from sonnet_core.database import borrow_db_session
from sonnet_core.database.crud import CrudConfig, CrudRepository


class WidgetService(CrudRepository[Widget, WidgetResponse]):
    crud_config = CrudConfig(
        db_model=Widget,
        response_model=WidgetResponse,
        lookup_field="slug",
        order_by="name",
    )


service = WidgetService()

with borrow_db_session():
    widget = service.get("sprocket")

The boundary owns the transaction -- nothing inside the block commits. See the usage guides for repositories, sessions, filtering, state machines and the readiness pipeline.

Documentation

• Usage -- docs/usage/index.md
• Design -- docs/design/index.md
• Workspace -- ../../docs/README.md

The web layer that builds on this package is sonnet-server.

License

Apache 2.0 -- see LICENSE.md.