sonnet-core 0.1.0__py3-none-any.whl

sonnet_core/__init__.py

@@ -0,0 +1,64 @@
+"""sonnet-core: framework-agnostic core library for Petrarca Labs services.
+
+Pure data-layer and logic building blocks with no web/server framework
+dependency. Public surface::
+
+    from sonnet_core import (
+        # ids
+        generate_id, to_base36,
+        # models
+        ModelBuilder, create_model, create_model_builder,
+        to_response_model, update_model_fields,
+        # schema
+        SchemaValidationError, ValidationResult, validate_instance, validate_schema,
+        combine_schemas, extract_schemas_from_model_infos,
+        # enums
+        str_enum_column,
+        # versioning
+        VALID_ALGORITHMS, DEFAULT_ALGORITHM, pick_latest, version_sort_key,
+    )
+"""
+
+from sonnet_core.enum_column import str_enum_column
+from sonnet_core.id_generator import generate_id, to_base36
+from sonnet_core.json_schema import (
+    SchemaValidationError,
+    ValidationResult,
+    validate_instance,
+    validate_schema,
+)
+from sonnet_core.model_builder import ModelBuilder, create_model, create_model_builder
+from sonnet_core.model_converter import to_response_model, update_model_fields
+from sonnet_core.schema_utils import combine_schemas, extract_schemas_from_model_infos
+from sonnet_core.version_sort import (
+    DEFAULT_ALGORITHM,
+    VALID_ALGORITHMS,
+    pick_latest,
+    version_sort_key,
+)
+
+__all__ = [
+    # ID generation
+    "generate_id",
+    "to_base36",
+    # Model builder / converter
+    "ModelBuilder",
+    "create_model",
+    "create_model_builder",
+    "to_response_model",
+    "update_model_fields",
+    # JSON schema
+    "SchemaValidationError",
+    "ValidationResult",
+    "validate_instance",
+    "validate_schema",
+    "combine_schemas",
+    "extract_schemas_from_model_infos",
+    # Enum column
+    "str_enum_column",
+    # Version ordering
+    "VALID_ALGORITHMS",
+    "DEFAULT_ALGORITHM",
+    "pick_latest",
+    "version_sort_key",
+]

sonnet_core/enum_column.py

@@ -0,0 +1,56 @@
+"""Helper for mapping a StrEnum to a plain VARCHAR column with value coercion.
+
+StrEnum fields are stored as their string *values* (not member names) in a
+plain VARCHAR column -- no native Postgres enum type and no CHECK constraint,
+so new enum values can be added without a migration.
+
+The key detail: SQLAlchemy's ``Enum`` type looks up by member *name* by
+default, but our StrEnums use lowercase values (``CREATED = "created"``).
+``values_callable`` makes it store and load by value, and the result
+processor coerces the stored string back into the enum instance on load --
+so the ORM object holds a real enum, not a bare string. This prevents the
+Pydantic V2 ``PydanticSerializationUnexpectedValue`` serializer warning that
+occurs when a model holding a bare string is dumped against an enum-typed
+field.
+"""
+
+from enum import StrEnum
+
+import sqlalchemy as sa
+
+
+def str_enum_column(
+    enum_cls: type[StrEnum],
+    *,
+    nullable: bool = False,
+    server_default: str | None = None,
+    length: int = 32,
+    index: bool = False,
+) -> sa.Column:
+    """Return a Column storing a StrEnum as a constraint-free VARCHAR by value.
+
+    Args:
+        enum_cls: The StrEnum subclass to map.
+        nullable: Whether the column allows NULL.
+        server_default: Optional server-side default (the enum *value* string).
+        length: VARCHAR length. Defaults to 32.
+        index: Whether to index the column.
+
+    Returns:
+        A SQLAlchemy Column that round-trips str <-> enum and emits no CHECK
+        constraint (plain VARCHAR), so enum values can be added without a
+        schema migration.
+    """
+    enum_type = sa.Enum(
+        enum_cls,
+        native_enum=False,
+        create_constraint=False,
+        length=length,
+        values_callable=lambda e: [member.value for member in e],
+    )
+    return sa.Column(
+        enum_type,
+        nullable=nullable,
+        server_default=server_default,
+        index=index,
+    )

sonnet_core/id_generator.py

@@ -0,0 +1,59 @@
+"""Utility functions for generating IDs."""
+
+import random
+import string
+import time
+
+
+def generate_id(length: int = 16, prefix: str = "") -> str:
+    """Generate a compact, time-sortable ID with an optional type prefix.
+
+    Produces a URL-safe, human-readable identifier that sorts roughly in
+    creation order (a millisecond timestamp is encoded first). With a prefix
+    it yields self-describing, Stripe-style typed IDs (e.g. "org_...").
+
+    The ID consists of:
+    - Optional prefix (e.g. "org_") -- not counted toward length
+    - Current timestamp in base36 (8-10 chars), giving time ordering
+    - Random string (remaining chars)
+
+    Note: uses non-cryptographic randomness. Suitable for entity keys, not
+    for unguessable security tokens.
+
+    Args:
+        length: The length of the timestamp+random part (default: 16). The
+            prefix is prepended and does not count toward this length.
+        prefix: Optional prefix to prepend (e.g. "org_"). Produces
+            self-describing IDs like "org_mltkrwu9XPqQ8bf8".
+
+    Returns:
+        A string containing the generated ID with the optional prefix.
+    """
+    # Get current timestamp in base36 (will be 8-10 chars)
+    timestamp = to_base36(int(time.time() * 1000))
+
+    # Generate random string for remaining characters
+    random_chars = string.ascii_letters + string.digits
+    random_part = "".join(random.choice(random_chars) for _ in range(length))
+
+    # Combine and ensure exactly the specified length, then prepend prefix
+    return prefix + (timestamp + random_part)[:length].ljust(length, "0")
+
+
+def to_base36(number: int) -> str:
+    """Convert a number to base36 representation.
+
+    Args:
+        number: The number to convert
+
+    Returns:
+        A string containing the base36 representation
+    """
+    alphabet = string.digits + string.ascii_lowercase
+    base36 = ""
+
+    while number:
+        number, i = divmod(number, 36)
+        base36 = alphabet[i] + base36
+
+    return base36 or "0"

sonnet_core/json_schema.py

@@ -0,0 +1,191 @@
+"""JSON Schema validation utilities.
+
+Thin wrapper around the ``jsonschema`` library. All JSON Schema
+validation in the application flows through this module so that the
+underlying library can be replaced without touching callers.
+
+Two concerns are addressed:
+
+1. **Meta-validation** -- verify that a dict is a valid JSON Schema
+   document conforming to Draft 2020-12.
+2. **Instance validation** -- verify that a JSON-compatible value
+   conforms to a given JSON Schema document, with optional external
+   ``$ref`` resolution via a caller-supplied callback.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from jsonschema import Draft202012Validator, SchemaError, ValidationError
+from referencing import Registry, Resource
+from referencing.exceptions import Unresolvable
+from referencing.jsonschema import DRAFT202012
+
+# -- Result types -----------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaValidationError:
+    """Single validation error with location context."""
+
+    message: str
+    path: list[str] = field(default_factory=list)
+    schema_path: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationResult:
+    """Outcome of a validation call.
+
+    ``valid`` is True when no errors were found. ``errors`` contains
+    structured error details when validation fails.
+    """
+
+    valid: bool
+    errors: list[SchemaValidationError] = field(default_factory=list)
+
+
+# -- Public API -------------------------------------------------------------
+
+
+def validate_schema(document: dict[str, Any]) -> ValidationResult:
+    """Validate that *document* is a valid JSON Schema (Draft 2020-12).
+
+    Unknown keywords (e.g. ``x-ui-widget``) are allowed per spec -- they
+    are treated as annotations and do not cause validation failures.
+
+    Args:
+        document: The schema document to validate.
+
+    Returns:
+        ValidationResult indicating success or listing errors.
+    """
+    try:
+        Draft202012Validator.check_schema(document)
+    except SchemaError as exc:
+        errors = [
+            SchemaValidationError(
+                message=exc.message,
+                path=[str(p) for p in exc.path],
+                schema_path=[str(p) for p in exc.schema_path],
+            ),
+        ]
+        return ValidationResult(valid=False, errors=errors)
+    return ValidationResult(valid=True)
+
+
+def validate_instance(
+    instance: Any,
+    schema: dict[str, Any],
+    resolve_ref: Callable[[str], dict[str, Any]] | None = None,
+) -> ValidationResult:
+    """Validate a JSON-compatible *instance* against a JSON Schema.
+
+    The schema is assumed to be valid (call :func:`validate_schema`
+    first if unsure). Collects all errors rather than failing on the
+    first one.
+
+    Local ``$ref`` references (``#/$defs/...``) are resolved
+    automatically by the underlying library. External ``$ref`` URIs
+    (e.g. ``urn:example:address``) require a *resolve_ref* callback that
+    maps a URI string to the referenced schema document. This keeps the
+    public API library-agnostic -- callers never import the underlying
+    ``referencing`` package.
+
+    Args:
+        instance: The value to validate (dict, list, scalar, ...).
+        schema: A valid JSON Schema document (Draft 2020-12).
+        resolve_ref: Optional callback that resolves an external ``$ref``
+            URI to a JSON Schema document (plain dict).  When *None*,
+            external ``$ref`` URIs will produce a validation error.
+            The callback should raise ``KeyError`` if the URI cannot be
+            resolved; this is translated into a validation error.
+
+    Returns:
+        ValidationResult indicating success or listing all errors.
+
+    Example::
+
+        # Schema that references an external definition by URI.
+        schema = {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "address": {"$ref": "urn:example:address"},
+            },
+            "required": ["name", "address"],
+        }
+
+        # A lookup function that returns the referenced schema dict.
+        # In practice this would call SchemaRegistryClient.get_schema().
+        def resolve_ref(uri: str) -> dict:
+            schemas = {
+                "urn:example:address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                    "required": ["street", "city"],
+                },
+            }
+            return schemas[uri]  # KeyError if unknown
+
+        result = validate_instance(
+            {"name": "Alice", "address": {"street": "1 Main St", "city": "Zurich"}},
+            schema,
+            resolve_ref=resolve_ref,
+        )
+        assert result.valid is True
+    """
+    registry = _build_registry(resolve_ref) if resolve_ref is not None else Registry()
+    validator = Draft202012Validator(schema, registry=registry)
+
+    try:
+        raw_errors: list[ValidationError] = sorted(
+            validator.iter_errors(instance),
+            key=lambda e: list(e.path),
+        )
+    except Unresolvable as exc:
+        # An external $ref could not be resolved.
+        return ValidationResult(
+            valid=False,
+            errors=[SchemaValidationError(message=f"Unresolvable $ref: {exc}")],
+        )
+
+    if not raw_errors:
+        return ValidationResult(valid=True)
+
+    errors = [
+        SchemaValidationError(
+            message=err.message,
+            path=[str(p) for p in err.path],
+            schema_path=[str(p) for p in err.schema_path],
+        )
+        for err in raw_errors
+    ]
+    return ValidationResult(valid=False, errors=errors)
+
+
+# -- Internal helpers -------------------------------------------------------
+
+
+def _build_registry(resolve_ref: Callable[[str], dict[str, Any]]) -> Registry:
+    """Build a ``referencing.Registry`` backed by *resolve_ref*.
+
+    The registry uses lazy retrieval: schemas are fetched on demand the
+    first time a ``$ref`` URI is encountered during validation. This
+    keeps the public API library-agnostic -- callers provide a plain
+    ``Callable[[str], dict]`` and never import ``referencing`` directly.
+    """
+
+    def _retrieve(uri: str) -> Resource:
+        # Let KeyError propagate -- referencing catches it and raises
+        # Unresolvable, which we handle in validate_instance.
+        contents = resolve_ref(uri)
+        return Resource.from_contents(contents, default_specification=DRAFT202012)
+
+    return Registry(retrieve=_retrieve)

sonnet_core/model_builder.py

@@ -0,0 +1,353 @@
+"""Model builder utilities for creating Pydantic models dynamically."""
+
+import types
+from typing import Any, Union, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic import create_model as pydantic_create_model
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    """Unwrap ``T | None`` to ``T``.
+
+    If the annotation is a Union of exactly one concrete type and
+    ``NoneType``, returns the concrete type. Otherwise returns the
+    annotation unchanged.
+    """
+    origin = get_origin(annotation)
+    if origin is Union or origin is types.UnionType:
+        args = [a for a in get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation
+
+
+class ModelBuilder:
+    """Builder class for creating models with a fluent API."""
+
+    def __init__(self, base_model: type[BaseModel]):
+        """Initialize the builder with a base model.
+
+        Args:
+            base_model: The base model to inherit from
+        """
+        self.base_model = base_model
+        self.model_name = None
+        self.included_fields = None
+        self.excluded_fields = None
+        self.required_fields: list[str] | None = None
+        self.model_config = None
+        self.field_overrides = {}
+        self.all_fields = True
+        self.api_model = False
+
+    def with_name(self, name: str) -> ModelBuilder:
+        """Set the name for the model.
+
+        Args:
+            name: Name for the new model
+
+        Returns:
+            Self for method chaining
+        """
+        self.model_name = name
+        return self
+
+    def include(self, fields: list[str]) -> ModelBuilder:
+        """Include only specified fields from the base model.
+
+        Args:
+            fields: List of field names to include
+
+        Returns:
+            Self for method chaining
+        """
+        self.included_fields = fields
+        self.excluded_fields = None
+        return self
+
+    def exclude(self, fields: list[str]) -> ModelBuilder:
+        """Exclude specified fields from the base model.
+
+        Args:
+            fields: List of field names to exclude
+
+        Returns:
+            Self for method chaining
+        """
+        self.excluded_fields = fields
+        self.included_fields = None
+        return self
+
+    def require(self, fields: list[str]) -> ModelBuilder:
+        """Mark fields as required (strip Optional and remove default).
+
+        Use this to promote nullable base-model fields to required in
+        derived API input models. The field's inner type is unwrapped
+        from ``T | None`` and the default is removed so Pydantic treats
+        it as required.
+
+        Args:
+            fields: List of field names to make required.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.required_fields = fields
+        return self
+
+    def with_config(self, config: dict[str, Any]) -> ModelBuilder:
+        """Set model configuration.
+
+        Args:
+            config: Dictionary with model configuration
+
+        Returns:
+            Self for method chaining
+        """
+        self.model_config = config
+        return self
+
+    def with_all_fields(self, all_fields: bool) -> ModelBuilder:
+        """Set whether to include all fields from the base model.
+
+        Only relevant if neither include nor exclude is specified.
+
+        Args:
+            all_fields: Whether to include all fields from the base model
+
+        Returns:
+            Self for method chaining
+        """
+        self.all_fields = all_fields
+        return self
+
+    def with_api_model(self, api_model: bool) -> ModelBuilder:
+        """Set whether this is an API model.
+
+        If true, will add {"extra": "forbid"} to the model config
+        unless explicitly overridden by with_config.
+
+        Args:
+            api_model: Whether this is an API model
+
+        Returns:
+            Self for method chaining
+        """
+        self.api_model = api_model
+        return self
+
+    def override_field(self, field_name: str, annotation: Any, default: Any = ...) -> ModelBuilder:
+        """Override a field's type and default value.
+
+        Args:
+            field_name: Name of the field to override
+            annotation: Type annotation for the field
+            default: Default value for the field
+
+        Returns:
+            Self for method chaining
+        """
+        self.field_overrides[field_name] = (annotation, default)
+        return self
+
+    def _get_field_default(self, field_info) -> Any:
+        """Extract the default value from a field.
+
+        Args:
+            field_info: Field information from the model
+
+        Returns:
+            Default value or ... if no default
+        """
+        return field_info.default if field_info.default is not ... else ...
+
+    def _validate_required_fields(self, required: set[str]) -> None:
+        """Raise ValueError if any required field name is not on the base model."""
+        for req in required:
+            if req not in self.base_model.model_fields:
+                msg = f"required_fields: '{req}' does not exist on {self.base_model.__name__}"
+                raise ValueError(msg)
+
+    def _resolve_field(
+        self,
+        field_name: str,
+        required: set[str],
+        fields: dict[str, tuple[Any, Any]],
+    ) -> None:
+        """Add a single field to the output dict, applying required promotion if needed.
+
+        When not promoting to required, the full FieldInfo is passed so that
+        aliases, serialization aliases, and other field metadata are preserved
+        in the derived model.
+        """
+        if field_name not in self.base_model.model_fields:
+            return
+        field_info = self.base_model.model_fields[field_name]
+        if field_name in required:
+            # Required promotion: strip Optional and remove default/FieldInfo.
+            # Aliases are intentionally dropped here -- required fields in
+            # Input models are typically populated by field name, not alias.
+            fields[field_name] = (_unwrap_optional(field_info.annotation), ...)
+        else:
+            # Preserve full FieldInfo so aliases and other metadata carry through.
+            fields[field_name] = (field_info.annotation, field_info)
+
+    def _get_included_fields(self) -> dict[str, tuple[Any, Any]]:
+        """Get fields to include based on include/exclude settings.
+
+        Returns:
+            Dictionary of field definitions
+        """
+        required = set(self.required_fields) if self.required_fields else set()
+        self._validate_required_fields(required)
+
+        fields: dict[str, tuple[Any, Any]] = {}
+
+        if self.included_fields is not None:
+            # Case 1: Only include specified fields
+            for field in self.included_fields:
+                self._resolve_field(field, required, fields)
+        elif self.excluded_fields is not None:
+            # Case 2: Include all fields except those explicitly excluded
+            for field in self.base_model.model_fields:
+                if field not in self.excluded_fields:
+                    self._resolve_field(field, required, fields)
+        elif self.all_fields:
+            # Case 3: Include all fields
+            for field in self.base_model.model_fields:
+                self._resolve_field(field, required, fields)
+
+        return fields
+
+    def _create_model(self, fields: dict[str, tuple[Any, Any]]) -> type[BaseModel]:
+        """Create a Pydantic model with the given fields.
+
+        Args:
+            fields: Dictionary of field definitions
+
+        Returns:
+            New Pydantic model
+        """
+        model_config = self.model_config or {}
+        if self.api_model and "extra" not in model_config:
+            model_config["extra"] = "forbid"
+        model = pydantic_create_model(self.model_name, __module__=__name__, **fields)
+        model.model_config.update(model_config)
+        return model
+
+    def build(self) -> type[BaseModel]:
+        """Build and return the model.
+
+        Returns:
+            A new Pydantic model with the selected fields
+
+        Raises:
+            ValueError: If model_name is not set
+        """
+        if not self.model_name:
+            raise ValueError("Model name must be set using with_name() before building")
+        fields = self._get_included_fields()
+        fields.update(self.field_overrides)
+        return self._create_model(fields)
+
+
+def create_model_builder(base_model: type[BaseModel]) -> ModelBuilder:
+    """Create a model builder for the given base model.
+
+    Args:
+        base_model: The base model to inherit from
+
+    Returns:
+        A ModelBuilder instance for fluent API usage
+    """
+    return ModelBuilder(base_model)
+
+
+def create_model(
+    base_model: type[BaseModel],
+    name: str,
+    fields: list[str] | None = None,
+    excluded_fields: list[str] | None = None,
+    required_fields: list[str] | None = None,
+    config: dict[str, Any] | None = None,
+    field_overrides: dict[str, tuple[Any, Any]] | None = None,
+    all_fields: bool = True,
+    api_model: bool = False,
+    **field_override_kwargs: Any,
+) -> type[BaseModel]:
+    """Create a model based on a base model with various customizations.
+
+    This is a unified function that can handle all model creation cases:
+    - Create a model with only specified fields (include)
+    - Create a model excluding specified fields (exclude)
+    - Create a complete model with all fields
+
+    Args:
+        base_model: The base model to inherit from
+        name: Name for the new model
+        fields: Optional list of field names to include (takes precedence over excluded_fields)
+        excluded_fields: Optional list of field names to exclude (only used if fields is None)
+        required_fields: Optional list of field names to make required. Strips
+            ``T | None`` to ``T`` and removes the default so Pydantic treats
+            the field as mandatory. Useful for Input models where the base
+            model has all fields nullable.
+        config: Optional model configuration
+        field_overrides: Optional field overrides as {field_name: (annotation, default)}
+        all_fields: Whether to include all fields from the base model (only used if fields and excluded_fields are None)
+        api_model: Whether this is an API model (if true, adds {"extra": "forbid"} to config unless explicitly overridden)
+        **field_override_kwargs: Direct field overrides as keyword arguments
+            Format: field_name=(annotation, default)
+
+    Returns:
+        A new Pydantic model with the selected fields
+
+    Examples:
+        # Create a model with only specific fields
+        OrganizationResponse = create_model(
+            OrganizationBase,
+            "OrganizationResponse",
+            fields=["id", "org_id", "name"],
+        )
+
+        # Create a model excluding specific fields
+        OrganizationInput = create_model(
+            OrganizationBase,
+            "OrganizationInput",
+            excluded_fields=["id", "org_id", "version"],
+        )
+
+        # Create an input model with required fields
+        UserInput = create_model(
+            UserBase,
+            "UserInput",
+            excluded_fields=["id", "user_id", "status"],
+            required_fields=["username"],
+            api_model=True,
+        )
+
+        # Create an API model with extra fields forbidden
+        OrganizationUpdate = create_model(
+            OrganizationBase,
+            "OrganizationUpdate",
+            api_model=True,
+        )
+    """
+    builder = create_model_builder(base_model).with_name(name).with_all_fields(all_fields)
+    if fields is not None:
+        builder = builder.include(fields)
+    elif excluded_fields is not None:
+        builder = builder.exclude(excluded_fields)
+    if required_fields:
+        builder = builder.require(required_fields)
+    if config:
+        builder = builder.with_config(config)
+    if field_overrides:
+        for field_name, (annotation, default) in field_overrides.items():
+            builder = builder.override_field(field_name, annotation, default)
+    for field_name, override in field_override_kwargs.items():
+        if isinstance(override, tuple) and len(override) == 2:
+            annotation, default = override
+            builder = builder.override_field(field_name, annotation, default)
+    builder = builder.with_api_model(api_model)
+    return builder.build()

sonnet_core/model_converter.py

@@ -0,0 +1,224 @@
+"""Utility functions for converting between database and API models."""
+
+from collections.abc import Callable
+from typing import Any, TypeVar, get_args, get_origin
+
+from pydantic import BaseModel
+from sqlmodel import SQLModel
+
+# Define generic type variables
+T = TypeVar("T", bound=SQLModel)  # Database model type
+R = TypeVar("R", bound=BaseModel)  # API response model type
+
+
+def update_model_fields(
+    model: SQLModel,
+    fields: dict[str, Any],
+    field_transformers: dict[str, Callable[[Any], Any]] | None = None,
+) -> None:
+    """Update model fields from a dictionary, applying optional transformations.
+
+    Only updates fields that are present in the ``fields`` dictionary.
+    This enables partial updates with the ``exclude_unset`` pattern.
+
+    Transformer functions are skipped when their corresponding value is
+    ``None`` -- e.g. a password hasher is not called when no new password
+    is provided.
+
+    Args:
+        model: The SQLModel instance to update.
+        fields: Dictionary of field names and values to update.
+        field_transformers: Optional mapping of field names to transformation
+            functions applied before assignment.
+            Example: ``{"password": password_service.hash_password}``
+    """
+    field_transformers = field_transformers or {}
+
+    for field_name, value in fields.items():
+        if not hasattr(model, field_name):
+            continue
+        if field_name in field_transformers:
+            if value is None:
+                continue  # skip transformer when no value supplied
+            value = field_transformers[field_name](value)
+        setattr(model, field_name, value)
+
+
+def _convert_to_dict(db_model: Any) -> dict:
+    """Convert a model instance to a dictionary."""
+    if db_model is None:
+        return {}
+    if isinstance(db_model, SQLModel):
+        return db_model.model_dump()
+    elif hasattr(db_model, "__dict__"):
+        return {k: v for k, v in db_model.__dict__.items() if not k.startswith("_")}
+    return {}
+
+
+def _convert_collection(items: list | set | tuple, target_model: type[BaseModel]) -> list:
+    """Convert a collection of items to a list of response models."""
+    return [to_response_model(item, target_model).model_dump() for item in items if item is not None]
+
+
+def _convert_single_item(item: Any, target_model: type[BaseModel]) -> dict:
+    """Convert a single item to a response model."""
+    if item is None:
+        return {}
+    return to_response_model(item, target_model).model_dump()
+
+
+def _get_nested_attribute(obj: Any, attr_path: str) -> tuple[Any, str, Any]:
+    """Get a nested attribute from an object.
+
+    Returns:
+        Tuple of (parent_object, final_attribute_name, attribute_value)
+    """
+    if not attr_path or obj is None:
+        return None, "", None
+    parts = attr_path.split(".")
+    current_obj = obj
+    # For simple attributes
+    if len(parts) == 1:
+        return obj, parts[0], getattr(obj, parts[0], None)
+    # Navigate through the object hierarchy for nested attributes
+    for part in parts[:-1]:
+        if hasattr(current_obj, part):
+            current_obj = getattr(current_obj, part)
+            if current_obj is None:
+                return None, parts[-1], None
+        else:
+            return None, parts[-1], None
+    return current_obj, parts[-1], getattr(current_obj, parts[-1], None)
+
+
+def _process_simple_mapping(db_model: Any, attr_name: str, target_model: type[BaseModel]) -> dict | None:
+    """Process a simple (non-nested) attribute mapping."""
+    if not hasattr(db_model, attr_name):
+        return None
+    value = getattr(db_model, attr_name)
+    if value is None:
+        return None
+    if isinstance(value, list | set | tuple):
+        return _convert_collection(value, target_model)
+    return _convert_single_item(value, target_model)
+
+
+def _process_nested_mapping(
+    db_model: Any, response_model_class: type[BaseModel], attr_path: str, target_model: type[BaseModel]
+) -> tuple[str, dict] | None:
+    """Process a nested attribute mapping.
+
+    Returns:
+        Tuple of (parent_field_name, updated_parent_dict) or None if mapping can't be applied
+    """
+    parent_obj, final_attr, value = _get_nested_attribute(db_model, attr_path)
+    if parent_obj is None or value is None:
+        return None
+    # Get the parent field name (first part of the path)
+    parent_field = attr_path.split(".")[0]
+    if parent_field not in response_model_class.model_fields:
+        return None
+    # Get the parent field type from the response model
+    parent_field_type = response_model_class.model_fields[parent_field].annotation
+    # Check if the parent field is a Pydantic model and has the nested attribute
+    if (
+        not isinstance(parent_field_type, type)
+        or not issubclass(parent_field_type, BaseModel)
+        or final_attr not in parent_field_type.model_fields
+    ):
+        return None
+    # Get the parent value from the database model
+    parent_value = getattr(db_model, parent_field)
+    if parent_value is None:
+        return None
+    # Convert the parent to its response model
+    parent_response = to_response_model(parent_value, parent_field_type)
+    # Convert the nested value
+    nested_value = to_response_model(value, target_model)
+    # Update the parent model with the nested value
+    parent_dict = parent_response.model_dump()
+    parent_dict[final_attr] = nested_value.model_dump()
+    return parent_field, parent_dict
+
+
+def _process_explicit_mappings(db_model: Any, response_model_class: type[BaseModel], mapping: dict[str, type[BaseModel]]) -> dict:
+    """Process explicit mappings for attributes."""
+    result = {}
+    for attr_path, target_model in mapping.items():
+        # Skip mappings for attributes that don't exist in the response model
+        if attr_path not in response_model_class.model_fields:
+            continue
+        # Handle simple attribute paths
+        if "." not in attr_path:
+            converted = _process_simple_mapping(db_model, attr_path, target_model)
+            if converted is not None:
+                result[attr_path] = converted
+        else:
+            # Handle nested attribute paths
+            nested_result = _process_nested_mapping(db_model, response_model_class, attr_path, target_model)
+            if nested_result:
+                parent_field, parent_dict = nested_result
+                result[parent_field] = parent_dict
+    return result
+
+
+def _process_nested_models(db_model: Any, response_model_class: type[BaseModel]) -> dict:
+    """Process nested models based on response model field types."""
+    result = {}
+    for field_name, field_info in response_model_class.model_fields.items():
+        field_type = field_info.annotation
+        # Skip if the db_model doesn't have this field or it's None
+        if not hasattr(db_model, field_name) or getattr(db_model, field_name) is None:
+            continue
+        value = getattr(db_model, field_name)
+        # Handle single nested model
+        if isinstance(field_type, type) and issubclass(field_type, BaseModel):
+            if isinstance(value, list | set | tuple):
+                result[field_name] = _convert_collection(value, field_type)
+            else:
+                result[field_name] = _convert_single_item(value, field_type)
+        # Handle list of nested models
+        elif (
+            get_origin(field_type) is list
+            and len(get_args(field_type)) > 0
+            and isinstance(get_args(field_type)[0], type)
+            and issubclass(get_args(field_type)[0], BaseModel)
+        ):
+            item_type = get_args(field_type)[0]
+            result[field_name] = _convert_collection(value, item_type)
+    return result
+
+
+def to_response_model[T: SQLModel, R: BaseModel](
+    db_model: T, response_model_class: type[R], mapping: dict[str, type[BaseModel]] | None = None
+) -> R:
+    """Convert a database model to an API response model.
+
+    This function handles nested objects and lists by recursively converting them
+    to the appropriate response model types. You can also specify explicit mappings
+    for nested objects.
+
+    Args:
+        db_model: The database model instance to convert
+        response_model_class: The API response model class to convert to
+        mapping: Optional dictionary mapping attribute paths to response model classes.
+                Example: {"items": ItemResponse, "owner.details": DetailsResponse}
+                Note: Mapped attributes must exist in the response model class.
+
+    Returns:
+        An instance of the API response model
+    """
+    if db_model is None:
+        return None
+    # Convert the database model to a dictionary
+    model_dict = _convert_to_dict(db_model)
+    # Process explicit mappings if provided
+    if mapping:
+        mapped_fields = _process_explicit_mappings(db_model, response_model_class, mapping)
+        model_dict.update(mapped_fields)
+    # Otherwise, check response model fields for nested objects
+    else:
+        nested_fields = _process_nested_models(db_model, response_model_class)
+        model_dict.update(nested_fields)
+    # Create the response model with model_validate
+    return response_model_class.model_validate(model_dict)

sonnet_core/schema_utils.py

@@ -0,0 +1,82 @@
+"""Schema Utilities - Common schema manipulation utilities."""
+
+from typing import Any
+
+
+def combine_schemas(
+    schemas: list[dict[str, Any]],
+    title: str = "Data Model",
+    description: str = "Complete data model for API management including entities and their relationships.",
+    schema_id: str = "https://sonnet-server.com/schemas/data.schema.json",
+) -> dict[str, Any]:
+    """Combine multiple JSON schemas into a single enriched schema using $defs format.
+
+    This function creates an enriched JSON Schema Draft 2020-12 compliant schema
+    that nests all individual schemas under the $defs property.
+
+    Args:
+        schemas: List of individual JSON schema objects to combine
+        title: Title for the combined schema (default: "Data Model")
+        description: Description for the combined schema
+        schema_id: $id value for the combined schema
+
+    Returns:
+        Combined schema in enriched $defs format
+
+    Example:
+        >>> schemas = [{"title": "Product", "type": "object", ...}, {"title": "Company", "type": "object", ...}]
+        >>> combined = combine_schemas(schemas)
+        >>> combined["title"]
+        'Data Model'
+        >>> combined["$defs"]["Product"]["title"]
+        'Product'
+    """
+    # Create enriched schema with $defs structure (JSON Schema Draft 2020-12)
+    enriched_schema = {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": schema_id,
+        "title": title,
+        "description": description,
+        "$defs": {},
+    }
+
+    # Add all schemas to $defs
+    for schema in schemas:
+        schema_title = schema.get("title")
+        if schema_title:
+            enriched_schema["$defs"][schema_title] = schema
+
+    return enriched_schema
+
+
+def extract_schemas_from_model_infos(model_infos: list[Any]) -> list[dict[str, Any]]:
+    """Extract JSON schemas from a list of model info objects.
+
+    Args:
+        model_infos: List of model info objects
+
+    Returns:
+        List of JSON schema dictionaries
+
+    Raises:
+        ValueError: If no JSON schema is available for a model
+    """
+    schemas = []
+    for model_info in model_infos:
+        # Try to get schema from common attributes
+        json_schema = getattr(model_info, "schema", None) or getattr(model_info, "json_schema", None)
+        if not json_schema:
+            raise ValueError(f"No JSON schema available for model: {getattr(model_info, 'name', 'unknown')}")
+
+        # Handle case where json_schema might be a string (JSON serialized)
+        if isinstance(json_schema, str):
+            import json
+
+            try:
+                json_schema = json.loads(json_schema)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Invalid JSON schema string for model {getattr(model_info, 'name', 'unknown')}: {e}") from e
+
+        schemas.append(json_schema)
+
+    return schemas

sonnet_core/version_sort.py

@@ -0,0 +1,138 @@
+"""Version comparison and sorting utilities.
+
+Provides a cross-cutting mechanism for determining "latest" among
+multiple versions of the same logical resource (identified by URI or
+name). Aligned with FHIR R5 CodeSystem.versionAlgorithm.
+
+Supported algorithms:
+    natural  -- natural sort (default). Splits on digit/non-digit
+                boundaries and compares segments numerically where
+                possible. Handles "2025", "10", "1.2.3" correctly.
+    semver   -- semantic versioning (major.minor.patch). Pre-release
+                labels sort lower than release.
+    integer  -- numeric cast. Non-numeric values sort to -inf.
+    date     -- ISO date string comparison (lexicographic on ISO dates).
+    alpha    -- case-insensitive alphabetical.
+
+Usage:
+    from sonnet_core.version_sort import pick_latest
+
+    latest = pick_latest(rows, key=lambda r: r.content_version,
+                         algorithm=r.version_algorithm)
+"""
+
+import re
+
+from loguru import logger
+
+VALID_ALGORITHMS = ("natural", "semver", "integer", "date", "alpha")
+DEFAULT_ALGORITHM = "natural"
+
+
+def _natural_sort_key(version: str) -> list:
+    """Split version string into numeric and non-numeric segments for natural comparison."""
+    parts = re.split(r"(\d+)", version)
+    return [int(p) if p.isdigit() else p.lower() for p in parts if p]
+
+
+def _semver_sort_key(version: str) -> tuple:
+    """Parse a semver-like string into a comparable tuple.
+
+    Handles major.minor.patch with optional pre-release suffix.
+    Non-conforming strings fall back to natural sort key.
+    """
+    match = re.match(r"^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-(.+))?$", version)
+    if not match:
+        return (0, 0, 0, 0, _natural_sort_key(version))
+    major = int(match.group(1))
+    minor = int(match.group(2) or 0)
+    patch = int(match.group(3) or 0)
+    # Pre-release sorts lower than release (release = no suffix = high).
+    pre = match.group(4)
+    pre_rank = 0 if pre else 1
+    pre_key = _natural_sort_key(pre) if pre else []
+    return (major, minor, patch, pre_rank, pre_key)
+
+
+def _integer_sort_key(version: str) -> int:
+    """Parse version as integer. Non-numeric values sort to lowest."""
+    try:
+        return int(version)
+    except ValueError, TypeError:
+        return -1
+
+
+def _date_sort_key(version: str) -> str:
+    """ISO date strings are lexicographically sortable."""
+    return version
+
+
+def _alpha_sort_key(version: str) -> str:
+    """Case-insensitive alphabetical comparison."""
+    return version.lower()
+
+
+def version_sort_key(version: str, algorithm: str = DEFAULT_ALGORITHM):
+    """Return a sort key for the given version string and algorithm.
+
+    Args:
+        version: The version string to produce a sort key for.
+        algorithm: One of the VALID_ALGORITHMS.
+
+    Returns:
+        A comparable value suitable for sorted() or max().
+    """
+    if algorithm == "natural":
+        return _natural_sort_key(version)
+    if algorithm == "semver":
+        return _semver_sort_key(version)
+    if algorithm == "integer":
+        return _integer_sort_key(version)
+    if algorithm == "date":
+        return _date_sort_key(version)
+    if algorithm == "alpha":
+        return _alpha_sort_key(version)
+    logger.warning("Unknown version_algorithm '{}', falling back to natural", algorithm)
+    return _natural_sort_key(version)
+
+
+def pick_latest(rows, *, version_key, algorithm_key=None, status_key=None, algorithm: str | None = None):
+    """Pick the latest row from a list, preferring active status and highest version.
+
+    Args:
+        rows: Iterable of row objects (must be non-empty).
+        version_key: Callable that extracts the version string from a row.
+        algorithm_key: Callable that extracts the version_algorithm from a row.
+                       Ignored if ``algorithm`` is explicitly provided.
+        status_key: Callable that extracts the status string from a row.
+                    When provided, active rows are preferred over non-active.
+        algorithm: Explicit algorithm override. When set, algorithm_key is ignored.
+
+    Returns:
+        The single "latest" row.
+
+    Raises:
+        ValueError: If rows is empty.
+    """
+    items = list(rows)
+    if not items:
+        raise ValueError("Cannot pick latest from empty list")
+    if len(items) == 1:
+        return items[0]
+
+    # Determine algorithm from the first row if not explicitly provided.
+    if algorithm is None and algorithm_key is not None:
+        algorithm = algorithm_key(items[0]) or DEFAULT_ALGORITHM
+    if algorithm is None:
+        algorithm = DEFAULT_ALGORITHM
+
+    def sort_key(row):
+        # Primary: active status preferred (1 = active, 0 = other).
+        active_rank = 0
+        if status_key is not None:
+            active_rank = 1 if status_key(row) == "active" else 0
+        # Secondary: version comparison.
+        ver = version_key(row) or ""
+        return (active_rank, version_sort_key(ver, algorithm))
+
+    return max(items, key=sort_key)

sonnet_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: sonnet-core
+Version: 0.1.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
+Provides-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"
+
+# sonnet-core
+
+Framework-agnostic core library for Petrarca Labs backend services.
+
+`sonnet-core` is the foundation layer beneath `sonnet-server`. It holds pure
+data-layer and logic building blocks that carry **no web/server framework
+dependency** (no FastAPI, uvicorn, Alembic, Typer, or Jinja2). It may depend on
+data-modeling libraries (Pydantic, SQLAlchemy, SQLModel) and pure utilities
+(jsonschema, arrow, loguru).
+
+## Layering
+
+```
+sonnet-core    (this package -- pure data/logic)
+   ^
+sonnet-server  (web/server framework)
+   ^
+sonnet-auth / sonnet-graph / sonnet-storage
+```
+
+## Contents
+
+- **ids** -- compact, time-sortable id generation (`generate_id`, `to_base36`).
+- **models** -- Pydantic/SQLModel model building and conversion
+  (`create_model`, `ModelBuilder`, `to_response_model`, `update_model_fields`).
+- **schema** -- JSON Schema validation helpers
+  (`validate_instance`, `validate_schema`, `ValidationResult`).
+- **enums** -- constraint-free enum columns (`str_enum_column`).
+- **versioning** -- version-string ordering (`pick_latest`).

sonnet_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sonnet_core/__init__.py,sha256=qebjNt95gJKHqzz_mL4864oWMnvv_H_wJM7qEunNDzg,1871
+sonnet_core/enum_column.py,sha256=B49zcEtzlAlRqg67FyZQAuP8XuNEKzH5-Ash-2B5IV0,1944
+sonnet_core/id_generator.py,sha256=xqXnnEPYDAHye3PwyivpDokwOeJsvljYta5dIHEwkiY,1985
+sonnet_core/json_schema.py,sha256=nj5FWTIC9Ufz_DTZhNmaSebgd7lkQIuzd6bIMs3tzZA,6718
+sonnet_core/model_builder.py,sha256=ZUefLdLLLblYCraRm6uUn1klfsYzOSMngkLlVmG8VOM,12391
+sonnet_core/model_converter.py,sha256=0kojI1g6w7yLRdF6YpTnYMf3DPXXmdZliI2qcDj1As8,9193
+sonnet_core/schema_utils.py,sha256=c0WWrFAgxPe64Jd5shVnLOY33115ektZQrU387gbGWw,2869
+sonnet_core/version_sort.py,sha256=fkWJ5q_0WwWgCSfhVcU5PQslNnDh5IlVP1V9mkXpSFQ,4975
+sonnet_core-0.1.0.dist-info/METADATA,sha256=D_UteTRlfnYFiX_b0hYd6W2mot32sK7nyJWLsgAa3pY,1924
+sonnet_core-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sonnet_core-0.1.0.dist-info/top_level.txt,sha256=msjeLzbQxJmq3Nouoz33OmHQKiiEO89uX8WOitDtzhk,12
+sonnet_core-0.1.0.dist-info/RECORD,,

sonnet_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sonnet_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sonnet_core