Metadata-Version: 2.4
Name: sonnet-core
Version: 0.3.0
Summary: Framework-agnostic core library for Petrarca Labs backend services (models, ids, schemas, state machines)
Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
License-Expression: Apache-2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.14
Description-Content-Type: text/markdown
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlmodel>=0.0.37
Requires-Dist: sqlalchemy>=2.0.48
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: arrow>=1.4.0
Requires-Dist: alembic>=1.18.4
Requires-Dist: tenacity>=9.1.4
Provides-Extra: filtering
Requires-Dist: lark>=1.3.1; extra == "filtering"
Provides-Extra: dev
Requires-Dist: sonnet-core[filtering]; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"

# 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

```bash
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:

```python
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.

```python
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`](docs/usage/index.md)
- **Design** -- [`docs/design/index.md`](docs/design/index.md)
- **Workspace** -- [`../../docs/README.md`](../../docs/README.md)

The web layer that builds on this package is
[`sonnet-server`](../sonnet-server/README.md).

## License

Apache 2.0 -- see [LICENSE.md](../../LICENSE.md).
