krons 0.1.0__py3-none-any.whl

kronos/specs/catalog/__init__.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Spec Catalog - Reusable field Specs for Node composition and DDL generation.
+
+Pre-defined Specs for common database patterns:
+- **ContentSpecs**: id, created_at, content, metadata, embedding
+- **AuditSpecs**: updated_at/by, deleted_at/by, is_deleted, version, hashes
+- **CommonSpecs**: name, slug, status, email, phone, tenant_id, settings
+
+Usage:
+    from kronos.specs.catalog import ContentSpecs, AuditSpecs
+
+    content_specs = ContentSpecs.get_specs(dim=1536)
+    audit_specs = AuditSpecs.get_specs(use_uuid=True)
+    all_specs = content_specs + audit_specs
+
+For custom Specs, use the factories directly:
+    from kronos.specs.factory import create_embedding_spec, create_content_spec
+
+    my_embedding = create_embedding_spec("embedding", dim=1536)
+    my_content = create_content_spec("payload", content_type=MyModel)
+"""
+
+from ._audit import AuditSpecs
+from ._common import CommonSpecs
+from ._content import ContentSpecs
+from ._enforcement import EnforcementLevel, EnforcementSpecs
+
+__all__ = (
+    "AuditSpecs",
+    "CommonSpecs",
+    "ContentSpecs",
+    "EnforcementLevel",
+    "EnforcementSpecs",
+)

kronos/specs/catalog/_audit.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Audit field Specs - tracking, versioning, soft delete, hashing."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from kronos.specs.operable import Operable
+from kronos.specs.spec import Spec
+from kronos.utils import now_utc
+
+
+class AuditSpecs(BaseModel):
+    updated_at: datetime = Field(default_factory=now_utc)
+    updated_by: str | None = None
+    is_active: bool = True
+    is_deleted: bool = False
+    deleted_at: datetime | None = None
+    deleted_by: str | None = None
+    version: int = Field(default=1, ge=0)
+    content_hash: str | None = None
+    integrity_hash: str | None = None
+
+    @classmethod
+    def get_specs(cls, use_uuid: bool) -> list[Spec]:
+        """Get list of audit Specs based on actor ID type."""
+        operable = Operable.from_structure(cls)
+        specs = {spec.name: spec for spec in operable.get_specs()}
+
+        if use_uuid:
+            specs["updated_by"] = Spec(UUID, name="updated_by").as_nullable()
+            specs["deleted_by"] = Spec(UUID, name="deleted_by").as_nullable()
+
+        return list(specs.values())

kronos/specs/catalog/_common.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Common field Specs - reusable patterns across domain entities."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from kronos.specs.operable import Operable
+from kronos.specs.spec import Spec
+
+
+class CommonSpecs(BaseModel):
+    """Common fields for domain entities."""
+
+    name: str
+    slug: str
+    status: str = "active"
+    email: str | None = None
+    phone: str | None = None
+    tenant_id: UUID
+    settings: dict[str, Any] | None = None
+    data: dict[str, Any] | None = None
+
+    @classmethod
+    def get_specs(cls, *, status_default: str = "active") -> list[Spec]:
+        """Get list of common Specs.
+
+        Args:
+            status_default: Default value for status field.
+        """
+        operable = Operable.from_structure(cls)
+        specs = {spec.name: spec for spec in operable.get_specs()}
+
+        # Override status default if different
+        if status_default != "active":
+            specs["status"] = Spec(str, name="status", default=status_default)
+
+        return list(specs.values())

kronos/specs/catalog/_content.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Content field Specs - identity, timestamps, content, metadata, embeddings."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+from kronos.specs.operable import Operable
+from kronos.specs.spec import Spec
+from kronos.types._sentinel import Unset, UnsetType
+from kronos.types.db_types import VectorMeta
+from kronos.utils import now_utc
+
+
+class ContentSpecs(BaseModel):
+    """Core content fields for elements/nodes."""
+
+    id: UUID = Field(default_factory=uuid4)
+    created_at: datetime = Field(default_factory=now_utc)
+    content: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+    embedding: list[float] | None = None
+
+    @classmethod
+    def get_specs(
+        cls,
+        *,
+        content_type: type | UnsetType = Unset,
+        dim: int | UnsetType = Unset,
+    ) -> list[Spec]:
+        """Get list of content Specs.
+
+        Args:
+            content_type: Type for content/metadata fields (default: dict).
+            dim: Embedding dimension. Unset = list[float], int = Vector[dim].
+        """
+        operable = Operable.from_structure(cls)
+        specs = {spec.name: spec for spec in operable.get_specs()}
+
+        # Override content/metadata type if specified
+        if content_type is not Unset:
+            specs["content"] = Spec(content_type, name="content").as_nullable()
+            specs["metadata"] = Spec(content_type, name="metadata").as_nullable()
+
+        # Override embedding with vector dimension if specified
+        if dim is not Unset and isinstance(dim, int):
+            specs["embedding"] = Spec(
+                list[float],
+                name="embedding",
+                embedding=VectorMeta(dim),
+            ).as_nullable()
+
+        return list(specs.values())

kronos/specs/catalog/_enforcement.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Enforcement levels and specs for policy evaluation."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from kronos.specs.operable import Operable
+from kronos.specs.spec import Spec
+from kronos.types.base import Enum
+from kronos.utils import now_utc
+
+__all__ = (
+    "EnforcementLevel",
+    "EnforcementSpecs",
+)
+
+
+class EnforcementLevel(Enum):
+    """How strictly to enforce policy violations.
+
+    HARD_MANDATORY: Blocks action, no override possible
+    SOFT_MANDATORY: Blocks action, but can be overridden with justification
+    ADVISORY: Warns but allows action to proceed
+    """
+
+    HARD_MANDATORY = "hard_mandatory"
+    SOFT_MANDATORY = "soft_mandatory"
+    ADVISORY = "advisory"
+
+    @classmethod
+    def is_blocking(cls, result: Any) -> bool:
+        """Check if policy result blocks the action."""
+        enforcement = getattr(result, "enforcement", "")
+        return enforcement in (
+            cls.HARD_MANDATORY.value,
+            cls.SOFT_MANDATORY.value,
+        )
+
+    @classmethod
+    def is_advisory(cls, result: Any) -> bool:
+        """Check if policy result is advisory (not blocking)."""
+        return getattr(result, "enforcement", "") == cls.ADVISORY.value
+
+
+class EnforcementSpecs(BaseModel):
+    """Fields for policy enforcement results."""
+
+    enforcement: str = EnforcementLevel.HARD_MANDATORY.value
+    policy_id: str
+    violation_code: str | None = None
+    evaluated_at: datetime = Field(default_factory=now_utc)
+    evaluation_ms: float = Field(default=0.0, ge=0.0)
+
+    @field_validator("enforcement", mode="before")
+    @classmethod
+    def _extract_enum_value(cls, v):
+        """Extract .value from enum members."""
+        return v.value if hasattr(v, "value") else v
+
+    @classmethod
+    def get_specs(cls) -> list[Spec]:
+        """Get list of enforcement Specs."""
+        operable = Operable.from_structure(cls)
+        return list(operable.get_specs())

kronos/specs/factory.py

@@ -0,0 +1,120 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Content field Specs - structured content, metadata, embeddings."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from kronos.specs.spec import Spec, not_sentinel
+from kronos.types import UnsetType
+from kronos.types._sentinel import Unset
+from kronos.types.base import is_sentinel
+
+
+def create_datetime_spec(name: str, *, use_default: bool) -> Spec:
+    from kronos.utils._utils import coerce_created_at, now_utc
+
+    return Spec(
+        datetime,
+        name=name,
+        default_factory=now_utc if use_default else Unset,
+        validator=lambda cls, v: coerce_created_at(v),
+    )
+
+
+def create_uuid_spec(name: str, *, use_default: bool) -> Spec:
+    from kronos.utils._utils import to_uuid
+
+    return Spec(
+        UUID,
+        name=name,
+        default_factory=uuid4 if use_default else Unset,
+        validator=lambda cls, v: to_uuid(v) if v is not None else None,
+    )
+
+
+def create_content_spec(
+    name: str = "content",
+    *,
+    content_type: type = Unset,
+    use_default: bool = False,
+    default_factory=Unset,
+) -> Spec:
+    content_type = dict if is_sentinel(content_type) else content_type
+    if use_default:
+        _df = default_factory if not_sentinel(default_factory) else content_type
+        return Spec(content_type, name=name, default_factory=_df)
+    return Spec(content_type, name=name)
+
+
+def create_embedding_spec(
+    name: str = "embedding",
+    *,
+    use_default: bool = False,
+    dim: int | UnsetType = Unset,
+) -> Spec:
+    """Create dimensioned embedding Spec
+
+    Args:
+        dim: Vector dimension (1536=OpenAI, 768=BERT, 384=MiniLM).
+        name: DB column name.
+
+    Returns:
+        Spec[Vector[dim]] for DDL generation with correct pgvector type.
+
+    Example:
+        create_embedding_spec(1536)  # -> Vector(1536) in DDL
+    """
+
+    if is_sentinel(dim):
+        if use_default:
+            return Spec(list[float], name=name, default_factory=list)
+        return Spec(list[float], name=name)
+
+    from kronos.specs.adapters.sql_ddl import Vector
+
+    return Spec(Vector[dim], name=name)
+
+
+def create_change_by_spec(name: str, *, use_uuid: bool = True):
+    """Create 'created_by'/'updated_by' Spec with UUID or str type.
+
+    Args:
+        name: Field name
+        use_uuid: True=UUID type, False=str type
+
+    Returns:
+        Spec for 'created_by'/'updated_by' field
+    """
+    if use_uuid:
+        return create_uuid_spec(name, use_default=False)
+    return Spec(str, name=name)
+
+
+def create_enumed_str_spec(name: str, *, default=None) -> Spec:
+    """Create a Spec that stores enum values as strings.
+
+    Args:
+        name: Field name.
+        enum_cls: Enum class (for documentation).
+        default: Default enum member or string value.
+
+    Returns:
+        Spec[str] with validator that extracts .value from enum members.
+    """
+    if default:
+        return Spec(
+            str,
+            name=name,
+            default=_extract_enum_value(None, default),
+            validator=_extract_enum_value,
+        )
+    return Spec(str, name=name, validator=_extract_enum_value)
+
+
+def _extract_enum_value(_cls, v, /):
+    """Extract .value from enum members."""
+    return v.value if hasattr(v, "value") else v

kronos/specs/operable.py

@@ -0,0 +1,314 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Self
+
+from kronos.protocols import Allowable, Hashable, implements
+from kronos.types._sentinel import MaybeUnset, Unset, UnsetType, is_unset, not_sentinel
+
+from .adapters.factory import AdapterType, get_adapter
+from .protocol import SpecAdapter
+from .spec import Spec
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+__all__ = ("Operable",)
+
+DEFAULT_ADAPTER: AdapterType = "pydantic"
+
+
+@implements(Hashable, Allowable)
+@dataclass(frozen=True, slots=True)
+class Operable:
+    """Ordered Spec collection for framework-agnostic schema definition.
+
+    Operable collects Spec objects into a semantic namespace with unique field names,
+    then delegates structure composition to framework-specific adapters (Pydantic, SQL, etc.).
+
+    Design:
+        - Immutable: frozen dataclass, specs cannot change after creation
+        - Ordered: field order preserved for serialization consistency
+        - Adapter-agnostic: same Operable works with any supported framework
+        - Composable: extend() for schema inheritance/override patterns
+
+    Attributes:
+        __op_fields__: Ordered tuple of Spec objects
+        __adapter_name__: Adapter identifier ("pydantic", "sql", "dataclass")
+        name: Optional schema name (used as default model name)
+
+    Usage:
+        # Define specs and compose into model
+        specs = [Spec(str, name="title"), Spec(int, name="count")]
+        op = Operable(specs, adapter="pydantic")
+        Model = op.compose_structure("Record")
+
+        # Extend existing schema
+        extended = op.extend([Spec(float, name="score")])
+
+        # Extract specs from existing model
+        op = Operable.from_structure(ExistingModel, "pydantic")
+
+    Adapter Interface:
+        All framework operations go through op.adapter:
+        - op.adapter.compose_structure(op, name) -> framework model class
+        - op.adapter.validate_instance(Model, data) -> validated instance
+        - op.adapter.extract_specs(Model) -> tuple of Specs
+
+    See Also:
+        Spec: Individual field specification
+        get_adapter: Factory for adapter classes
+    """
+
+    __op_fields__: tuple[Spec, ...]
+    __adapter_name__: str
+    name: MaybeUnset[str | None] = Unset
+
+    def __init__(
+        self,
+        specs: tuple[Spec, ...] | list[Spec] = tuple(),
+        *,
+        name: MaybeUnset[str | None] = Unset,
+        adapter: AdapterType = DEFAULT_ADAPTER,
+    ):
+        """Initialize Operable with Spec collection and adapter.
+
+        Args:
+            specs: Tuple or list of Spec objects (order preserved)
+            name: Schema name (defaults model name in compose_structure)
+            adapter: Framework adapter ("pydantic", "sql", "dataclass")
+
+        Raises:
+            TypeError: If specs contains non-Spec objects
+            ValueError: If duplicate field names detected
+        """
+        if isinstance(specs, list):
+            specs = tuple(specs)
+
+        for i, item in enumerate(specs):
+            if not isinstance(item, Spec):
+                raise TypeError(
+                    f"All specs must be Spec objects, got {type(item).__name__} at index {i}"
+                )
+
+        names = [s.name for s in specs if s.name is not None]
+        if len(names) != len(set(names)):
+            from collections import Counter
+
+            duplicates = [name for name, count in Counter(names).items() if count > 1]
+            raise ValueError(
+                f"Duplicate field names found: {duplicates}. Each spec must have a unique name."
+            )
+
+        object.__setattr__(self, "__op_fields__", specs)
+        object.__setattr__(self, "__adapter_name__", adapter)
+        object.__setattr__(self, "name", name)
+
+    @property
+    def adapter(self) -> type[SpecAdapter]:
+        """Get adapter class for this Operable."""
+        return get_adapter(self.__adapter_name__)
+
+    def allowed(self) -> frozenset[str]:
+        """Return set of valid field names from all specs."""
+        return frozenset({i.name for i in self.__op_fields__})
+
+    def check_allowed(self, *args, as_boolean: bool = False):
+        """Validate field names exist in this Operable.
+
+        Args:
+            *args: Field names to check
+            as_boolean: If True, return bool instead of raising
+
+        Returns:
+            True if all names valid, False if as_boolean=True and invalid
+
+        Raises:
+            ValueError: If any name invalid and as_boolean=False
+        """
+        if not set(args).issubset(self.allowed()):
+            if as_boolean:
+                return False
+            raise ValueError(
+                f"Some specified fields are not allowed: {set(args).difference(self.allowed())}"
+            )
+        return True
+
+    def get(self, key: str, /, default=Unset) -> MaybeUnset[Spec]:
+        """Get Spec by field name, returning default if not found."""
+        if not self.check_allowed(key, as_boolean=True):
+            return default
+        for i in self.__op_fields__:
+            if i.name == key:
+                return i
+        return default
+
+    def extend(
+        self,
+        specs: list[Spec] | tuple[Spec, ...],
+        *,
+        name: MaybeUnset[str | None] = Unset,
+        adapter: AdapterType | None = None,
+    ) -> Operable:
+        """Create new Operable with additional specs (overrides existing by name).
+
+        Args:
+            specs: Additional Spec objects to append/override
+            name: Override name (defaults to self.name)
+            adapter: Override adapter (defaults to self.__adapter_name__)
+
+        Returns:
+            New Operable with combined specs. If a spec in `specs` has the
+            same name as an existing spec, the new spec replaces the old one.
+
+        Example:
+            extended = AUDIT_SPECS.extend([
+                spec_embedding(1536),
+                spec_content(JobContent),  # Overrides SPEC_CONTENT_JSONB
+            ])
+            Model = extended.compose_structure("Job", include={...}, base_type=Node)
+        """
+        new_names = {s.name for s in specs if s.name}
+        combined = [s for s in self.__op_fields__ if s.name not in new_names]
+        combined.extend(specs)
+
+        return Operable(
+            combined,
+            name=name or self.name,
+            adapter=adapter or self.__adapter_name__,
+        )
+
+    def get_specs(
+        self,
+        *,
+        include: set[str] | UnsetType = Unset,
+        exclude: set[str] | UnsetType = Unset,
+    ) -> tuple[Spec, ...]:
+        """Get filtered specs by include/exclude field names.
+
+        Args:
+            include: Only return specs with these names (mutually exclusive with exclude)
+            exclude: Exclude specs with these names (mutually exclusive with include)
+
+        Returns:
+            Filtered tuple of Spec objects
+
+        Raises:
+            ValueError: If both include and exclude specified, or invalid names
+        """
+        if not_sentinel(include) and not_sentinel(exclude):
+            raise ValueError("Cannot specify both include and exclude")
+
+        if not_sentinel(include):
+            if self.check_allowed(*include, as_boolean=True) is False:
+                raise ValueError(
+                    "Some specified fields are not allowed: "
+                    f"{set(include).difference(self.allowed())}"
+                )
+            return tuple(self.get(i) for i in include if not is_unset(self.get(i)))  # type: ignore[misc]
+
+        if not_sentinel(exclude):
+            _discards = {self.get(i) for i in exclude if not is_unset(self.get(i))}
+            return tuple(s for s in self.__op_fields__ if s not in _discards)
+
+        return self.__op_fields__
+
+    def compose_structure(
+        self,
+        name: str | UnsetType = Unset,
+        *,
+        include: set[str] | UnsetType = Unset,
+        exclude: set[str] | UnsetType = Unset,
+        **kw,
+    ):
+        """Compose a typed structure from specs via adapter.
+
+        Args:
+            name: Structure name (default: self.name or "DynamicStructure")
+            include: Only include these field names
+            exclude: Exclude these field names
+            **kw: Additional adapter-specific kwargs
+
+        Returns:
+            Framework structure (e.g., Pydantic BaseModel, SQL DDL)
+        """
+        # Determine structure name: explicit > operable.name > fallback
+        if is_unset(name):
+            structure_name = self.name if self.name else "DynamicStructure"
+        else:
+            structure_name = name
+        return self.adapter.compose_structure(
+            self,
+            structure_name,
+            include=include,
+            exclude=exclude,
+            **kw,
+        )
+
+    @classmethod
+    def from_structure(
+        cls,
+        structure: type[BaseModel],
+        *,
+        adapter: AdapterType = DEFAULT_ADAPTER,
+        name: MaybeUnset[str | None] = Unset,
+    ) -> Self:
+        """Create Operable by extracting specs from a structure.
+
+        Disassembles a structure and returns an Operable with Specs
+        representing top-level fields.
+
+        Args:
+            structure: Structure class to extract specs from (e.g., Pydantic BaseModel)
+            name: Optional operable name (defaults to structure class name)
+            adapter: Adapter type for the operable
+
+        Returns:
+            Operable with Specs for each top-level field
+
+        Example:
+            >>> class MyModel(BaseModel):
+            ...     name: str
+            ...     age: int = 0
+            ...     tags: list[str] | None = None
+            >>> op = Operable.from_structure(MyModel, "pydantic")
+            >>> op.allowed()  # {'name', 'age', 'tags'}
+        """
+        specs = get_adapter(adapter).extract_specs(structure)
+        return cls(
+            specs=specs,
+            name=name or structure.__name__,
+            adapter=adapter,
+        )
+
+    def validate_instance(self, structure: Any, data: dict, /) -> Any:
+        """Validate data instance against this Operable's structure.
+
+        Args:
+            instance: Data instance to validate (e.g., dict, dataclass)
+
+        Returns:
+            Validated instance (may be transformed by adapter)
+
+        Raises:
+            ValidationError: If validation fails
+        """
+        specs = self.adapter.extract_specs(structure)
+        if not {s.name for s in specs}.issubset(self.allowed()):
+            raise ValueError("Structure contains fields not defined in this Operable")
+
+        return self.adapter.validate_instance(structure, data)
+
+    def dump_instance(self, instance: Any) -> dict:
+        """Dump data instance to dict via this Operable's structure.
+
+        Args:
+            instance: Data instance to dump (e.g., Pydantic model, dataclass)
+
+        Returns:
+            Dict representation of the instance
+        """
+        return self.adapter.dump_instance(instance, self)