sonnet-core 0.1.0__tar.gz

sonnet_core-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,29 @@
+# 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/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonnet-core"
+version = "0.1.0"
+authors = [
+    { name = "Wolfgang Miller", email = "wolfgang.miller@petrarca-labs.com" },
+]
+description = "Framework-agnostic core library for Petrarca Labs backend services (models, ids, schemas, state machines)"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.14,<4.0"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "loguru>=0.7.3",
+    "pydantic>=2.0",
+    "sqlmodel>=0.0.37",
+    "sqlalchemy>=2.0.48",
+    "jsonschema>=4.23.0",
+    "arrow>=1.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: marks tests as unit tests (default)",
+    "integration: marks tests as integration tests",
+]
+testpaths = ["tests"]
+addopts = [
+    "-m unit",
+    "--strict-markers",
+    "--import-mode=importlib",
+]

sonnet_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sonnet_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)