krons 0.1.0__py3-none-any.whl

kronos/types/db_types.py

@@ -0,0 +1,260 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Type annotations for database fields.
+
+Provides semantic typing for foreign keys and vector embeddings:
+    FK[Model]   - Foreign key references to entity types
+    Vector[dim] - pgvector embeddings with dimension
+
+Extraction:
+    extract_kron_db_meta(source, metas="BOTH")
+        Unified extraction from FieldInfo, annotations, or Spec objects.
+"""
+
+from __future__ import annotations
+
+import types
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+from uuid import UUID
+
+from kronos.types._sentinel import Unset, UnsetType, not_sentinel
+
+
+def _is_field_info(obj: Any) -> bool:
+    """Runtime check for Pydantic FieldInfo without hard import."""
+    return type(obj).__name__ == "FieldInfo" and hasattr(obj, "metadata")
+
+
+__all__ = [
+    "FK",
+    "FKMeta",
+    "Vector",
+    "VectorMeta",
+    "extract_kron_db_meta",
+]
+
+
+# =============================================================================
+# Foreign Key
+# =============================================================================
+
+
+class FKMeta:
+    """Metadata for foreign key fields.
+
+    Carries:
+    - model: Referenced Entity/Node class (or string for forward refs)
+    - column: Referenced column (default "id")
+    - on_delete/on_update: Referential actions
+    - deferrable/initially_deferred: Constraint deferral
+
+    Example:
+        tenant_id: FK[Tenant]  # FKMeta(Tenant, "id", "CASCADE", "CASCADE")
+    """
+
+    __slots__ = (
+        "model",
+        "column",
+        "on_delete",
+        "on_update",
+        "deferrable",
+        "initially_deferred",
+    )
+
+    def __init__(
+        self,
+        model: type | str,
+        column: str = "id",
+        on_delete: str = "CASCADE",
+        on_update: str = "CASCADE",
+        deferrable: bool = False,
+        initially_deferred: bool = False,
+    ):
+        self.model = model
+        self.column = column
+        self.on_delete = on_delete
+        self.on_update = on_update
+        self.deferrable = deferrable
+        self.initially_deferred = initially_deferred
+
+    @property
+    def table_name(self) -> str:
+        """Get referenced table name from model's config or convention."""
+        if isinstance(self.model, str):
+            return self.model.lower() + "s"
+        if hasattr(self.model, "node_config"):
+            config = self.model.node_config
+            if config and hasattr(config, "table_name"):
+                return config.table_name
+        if hasattr(self.model, "_table_name"):
+            return self.model._table_name
+        return self.model.__name__.lower() + "s"
+
+    @property
+    def is_resolved(self) -> bool:
+        """Check if FK reference has been resolved to a class."""
+        return not isinstance(self.model, str)
+
+    def resolve(self, model_cls: type) -> None:
+        """Resolve string reference to actual class."""
+        self.model = model_cls
+
+    def __repr__(self) -> str:
+        name = self.model if isinstance(self.model, str) else self.model.__name__
+        return f"FK[{name}]"
+
+
+class _FK:
+    """Foreign key type annotation: FK[Model] -> Annotated[UUID, FKMeta(Model)]."""
+
+    def __class_getitem__(cls, model: type | str) -> Any:
+        return Annotated[UUID, FKMeta(model)]
+
+
+FK = _FK
+
+
+# =============================================================================
+# Vector (pgvector)
+# =============================================================================
+
+
+class VectorMeta:
+    """Metadata for vector embedding fields.
+
+    Carries dimension for pgvector VECTOR(dim) type.
+
+    Example:
+        embedding: Vector[1536]  # VectorMeta(1536)
+    """
+
+    __slots__ = ("dim",)
+
+    def __init__(self, dim: int):
+        if dim <= 0:
+            raise ValueError(f"Vector dimension must be positive, got {dim}")
+        self.dim = dim
+
+    def __repr__(self) -> str:
+        return f"Vector[{self.dim}]"
+
+
+class _Vector:
+    """Vector type annotation: Vector[dim] -> Annotated[list[float], VectorMeta(dim)]."""
+
+    def __class_getitem__(cls, dim: int) -> Any:
+        return Annotated[list[float], VectorMeta(dim)]
+
+
+Vector = _Vector
+
+
+# =============================================================================
+# Extraction
+# =============================================================================
+
+# Return type aliases for extract_kron_db_meta
+_MetaResult = FKMeta | VectorMeta | UnsetType
+_BothResult = tuple[FKMeta | UnsetType, VectorMeta | UnsetType]
+
+
+def _find_in_annotation(annotation: Any, meta_type: type) -> Any | None:
+    """Find metadata of given type in an annotation (Annotated or Union)."""
+    # Direct Annotated[T, Meta(...)]
+    if get_origin(annotation) is Annotated:
+        for arg in get_args(annotation):
+            if isinstance(arg, meta_type):
+                return arg
+
+    # Union (T | None) with Annotated members
+    origin = get_origin(annotation)
+    if origin is Union or isinstance(annotation, types.UnionType):
+        for member in get_args(annotation):
+            if get_origin(member) is Annotated:
+                for arg in get_args(member):
+                    if isinstance(arg, meta_type):
+                        return arg
+
+    return None
+
+
+def _find_in_field_info(field_info: Any, meta_type: type) -> Any | None:
+    """Find metadata of given type in a Pydantic FieldInfo."""
+    # Pydantic v2: metadata list
+    if hasattr(field_info, "metadata"):
+        for item in field_info.metadata:
+            if isinstance(item, meta_type):
+                return item
+            # Pydantic may store Annotated types in metadata
+            if get_origin(item) is Annotated:
+                found = _find_in_annotation(item, meta_type)
+                if found is not None:
+                    return found
+
+    # Fallback: check annotation
+    annotation = getattr(field_info, "annotation", None)
+    if annotation is not None:
+        return _find_in_annotation(annotation, meta_type)
+
+    return None
+
+
+def extract_kron_db_meta(
+    from_: Any,
+    metas: Literal["FK", "Vector", "BOTH"] = "BOTH",
+) -> _MetaResult | _BothResult:
+    """Extract FK and/or Vector metadata from a source.
+
+    Unified extraction dispatching on source type:
+    - FieldInfo: searches Pydantic metadata and annotation
+    - type/annotation: searches Annotated/Union structure
+    - Spec: reads spec metadata directly
+
+    Args:
+        from_: FieldInfo, type annotation, or Spec instance
+        metas: What to extract - "FK", "Vector", or "BOTH"
+
+    Returns:
+        "FK" or "Vector": The meta object or Unset if not found
+        "BOTH": Tuple of (fk_meta_or_Unset, vector_meta_or_Unset)
+    """
+    fk: FKMeta | UnsetType = Unset
+    vec: VectorMeta | UnsetType = Unset
+
+    if _is_field_info(from_):
+        if metas in ("FK", "BOTH"):
+            fk = _find_in_field_info(from_, FKMeta) or Unset
+        if metas in ("Vector", "BOTH"):
+            vec = _find_in_field_info(from_, VectorMeta) or Unset
+
+    elif get_origin(from_) is not None or isinstance(from_, type):
+        # Raw type annotation
+        if metas in ("FK", "BOTH"):
+            fk = _find_in_annotation(from_, FKMeta) or Unset
+        if metas in ("Vector", "BOTH"):
+            vec = _find_in_annotation(from_, VectorMeta) or Unset
+
+    else:
+        # Try Spec (lazy import to avoid circular)
+        from kronos.specs.spec import Spec
+
+        if isinstance(from_, Spec):
+            if metas in ("FK", "BOTH"):
+                fk_val = from_.get("as_fk", Unset)
+                if not_sentinel(fk_val, {"none"}) and isinstance(fk_val, FKMeta):
+                    fk = fk_val
+            if metas in ("Vector", "BOTH"):
+                vec_val = from_.get("embedding", Unset)
+                if not_sentinel(vec_val, {"none"}) and isinstance(vec_val, VectorMeta):
+                    vec = vec_val
+        else:
+            raise TypeError(
+                f"from_ must be FieldInfo, type annotation, or Spec, got {type(from_).__name__}"
+            )
+
+    if metas == "FK":
+        return fk
+    if metas == "Vector":
+        return vec
+    return (fk, vec)

kronos/types/identity.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Semantic UUID typing for type-safe entity identification.
+
+Provides ID[T] syntax for associating UUIDs with specific model types,
+enabling compile-time type checking and runtime semantic clarity.
+
+Usage:
+    from kronos.types import ID
+
+    user_id: ID[User] = uuid4()
+    org_id: ID[Organization] = uuid4()
+
+    # Type checker distinguishes these despite both being UUID at runtime
+"""
+
+from typing import Annotated
+from uuid import UUID
+
+__all__ = ("ID",)
+
+
+class _IDMeta(type):
+    """Metaclass enabling ID[T] syntax for semantic UUID typing.
+
+    At runtime: ID[Model] returns Annotated[UUID, ("ID", Model)]
+    For type checkers: Provides semantic distinction between UUID types.
+
+    This allows code to express intent clearly:
+        user_id: ID[User]      # A UUID that identifies a User
+        tenant_id: ID[Tenant]  # A UUID that identifies a Tenant
+
+    Both are UUIDs at runtime, but type checkers can distinguish them.
+    """
+
+    def __getitem__(cls, item: type) -> type:
+        return Annotated[UUID, ("ID", item)]
+
+
+class ID(UUID, metaclass=_IDMeta):
+    """Semantic UUID type with model association.
+
+    ID[T] creates a type annotation that:
+    - At runtime: Is equivalent to UUID
+    - For type checkers: Associates the UUID with model type T
+
+    This enables self-documenting code and catches type mismatches:
+
+        class User(Node): ...
+        class Tenant(Node): ...
+
+        def get_user(user_id: ID[User]) -> User: ...
+        def get_tenant(tenant_id: ID[Tenant]) -> Tenant: ...
+
+        uid: ID[User] = uuid4()
+        tid: ID[Tenant] = uuid4()
+
+        get_user(uid)   # OK
+        get_user(tid)   # Type error: expected ID[User], got ID[Tenant]
+
+    The semantic typing is purely for documentation and static analysis;
+    at runtime, ID[User] and ID[Tenant] are both just UUIDs.
+    """
+
+    pass

kronos/utils/__init__.py

@@ -0,0 +1,40 @@
+from ._hash import (
+    GENESIS_HASH,
+    MAX_HASH_INPUT_BYTES,
+    HashAlgorithm,
+    compute_chain_hash,
+    compute_hash,
+    hash_obj,
+)
+from ._json_dump import json_dump, json_dumpb, json_lines_iter
+from ._to_list import to_list
+from ._to_num import to_num
+from ._utils import (
+    async_synchronized,
+    coerce_created_at,
+    create_path,
+    extract_types,
+    get_bins,
+    import_module,
+    is_import_installed,
+    load_type_from_string,
+    now_utc,
+    register_type_prefix,
+    synchronized,
+    to_uuid,
+)
+from .concurrency import alcall, is_coro_func
+from .fuzzy import (
+    SimilarityAlgo,
+    extract_json,
+    fuzzy_json,
+    fuzzy_match_keys,
+    string_similarity,
+    to_dict,
+)
+from .sql._sql_validation import (
+    MAX_IDENTIFIER_LENGTH,
+    SAFE_IDENTIFIER_PATTERN,
+    sanitize_order_by,
+    validate_identifier,
+)

kronos/utils/_hash.py

@@ -0,0 +1,234 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import hashlib
+from collections.abc import Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from ._json_dump import json_dumpb
+from ._lazy_init import LazyInit
+
+if TYPE_CHECKING:
+    from hashlib import _Hash
+
+__all__ = (
+    "GENESIS_HASH",
+    "HashAlgorithm",
+    "compute_chain_hash",
+    "compute_hash",
+    "hash_obj",
+)
+
+_lazy = LazyInit()
+PydanticBaseModel = None
+
+
+def _do_init() -> None:
+    """Lazy-initialize Pydantic BaseModel reference."""
+    global PydanticBaseModel
+    from pydantic import BaseModel
+
+    PydanticBaseModel = BaseModel
+
+
+_PRIMITIVE_TYPES = (str, int, float, bool, type(None))
+_TYPE_MARKER_DICT = 0
+_TYPE_MARKER_LIST = 1
+_TYPE_MARKER_TUPLE = 2
+_TYPE_MARKER_SET = 3
+_TYPE_MARKER_FROZENSET = 4
+_TYPE_MARKER_PYDANTIC = 5
+
+
+def _generate_hashable_representation(item: Any) -> Any:
+    """Convert object to stable, order-independent hashable representation.
+
+    Recursively transforms dicts/sets into sorted tuples with type markers
+    to ensure consistent hashing regardless of insertion order.
+    """
+    if isinstance(item, _PRIMITIVE_TYPES):
+        return item
+
+    if PydanticBaseModel and isinstance(item, PydanticBaseModel):
+        return (
+            _TYPE_MARKER_PYDANTIC,
+            _generate_hashable_representation(item.model_dump()),
+        )
+
+    if isinstance(item, dict):
+        return (
+            _TYPE_MARKER_DICT,
+            tuple(
+                (str(k), _generate_hashable_representation(v))
+                for k, v in sorted(item.items(), key=lambda x: str(x[0]))
+            ),
+        )
+
+    if isinstance(item, list):
+        return (
+            _TYPE_MARKER_LIST,
+            tuple(_generate_hashable_representation(elem) for elem in item),
+        )
+
+    if isinstance(item, tuple):
+        return (
+            _TYPE_MARKER_TUPLE,
+            tuple(_generate_hashable_representation(elem) for elem in item),
+        )
+
+    if isinstance(item, frozenset):
+        try:
+            sorted_elements = sorted(list(item))
+        except TypeError:
+            sorted_elements = sorted(list(item), key=lambda x: (str(type(x)), str(x)))
+        return (
+            _TYPE_MARKER_FROZENSET,
+            tuple(_generate_hashable_representation(elem) for elem in sorted_elements),
+        )
+
+    if isinstance(item, set):
+        try:
+            sorted_elements = sorted(list(item))
+        except TypeError:
+            sorted_elements = sorted(list(item), key=lambda x: (str(type(x)), str(x)))
+        return (
+            _TYPE_MARKER_SET,
+            tuple(_generate_hashable_representation(elem) for elem in sorted_elements),
+        )
+
+    with contextlib.suppress(Exception):
+        return str(item)
+    with contextlib.suppress(Exception):
+        return repr(item)
+
+    return f"<unhashable:{type(item).__name__}:{id(item)}>"
+
+
+def hash_obj(data: Any, strict: bool = False) -> int:
+    """Generate stable int hash for Python __hash__() protocol.
+
+    Use for: set/dict membership, deduplication, __hash__ implementations.
+    NOT for: cryptographic integrity, content verification (use compute_hash).
+
+    Args:
+        data: Any data structure (dicts, lists, Pydantic models, nested).
+        strict: Deep-copy data before hashing to prevent mutation effects.
+
+    Returns:
+        Stable int hash suitable for hash-based collections.
+
+    Raises:
+        TypeError: If generated representation is not hashable.
+    """
+    _lazy.ensure(_do_init)
+
+    data_to_process = data
+    if strict:
+        data_to_process = copy.deepcopy(data)
+
+    hashable_repr = _generate_hashable_representation(data_to_process)
+
+    try:
+        return hash(hashable_repr)
+    except TypeError as e:
+        raise TypeError(
+            f"The generated representation for the input data was not hashable. "
+            f"Input type: {type(data).__name__}, Representation type: {type(hashable_repr).__name__}. "
+            f"Original error: {e}"
+        )
+
+
+MAX_HASH_INPUT_BYTES = 10 * 1024 * 1024
+"""Max hash input (10MB). SOC2 CC7.1 DoS prevention."""
+
+GENESIS_HASH: str = "GENESIS"
+"""Sentinel for first entry in hash chain."""
+
+
+class HashAlgorithm(Enum):
+    """NIST FIPS 180-4 compliant hash algorithms for cryptographic integrity."""
+
+    SHA256 = "sha256"
+    SHA384 = "sha384"
+    SHA512 = "sha512"
+
+    def get_hasher(self) -> Callable[..., _Hash]:
+        """Return hashlib constructor for this algorithm."""
+        return {
+            HashAlgorithm.SHA256: hashlib.sha256,
+            HashAlgorithm.SHA384: hashlib.sha384,
+            HashAlgorithm.SHA512: hashlib.sha512,
+        }[self]
+
+    @property
+    def digest_size(self) -> int:
+        """Digest size in bytes (32/48/64 for SHA256/384/512)."""
+        return {
+            HashAlgorithm.SHA256: 32,
+            HashAlgorithm.SHA384: 48,
+            HashAlgorithm.SHA512: 64,
+        }[self]
+
+
+def compute_hash(
+    obj: dict | str | bytes | Any,
+    algorithm: HashAlgorithm = HashAlgorithm.SHA256,
+    none_as_valid: bool = False,
+) -> str:
+    """Compute cryptographic hash for content integrity verification.
+
+    Use for: content integrity, tamper detection, evidence chains.
+    NOT for: __hash__ protocol, set/dict membership (use hash_obj).
+
+    Args:
+        obj: Data to hash (dict, str, bytes, or JSON-serializable).
+        algorithm: Hash algorithm (default SHA-256).
+        none_as_valid: Treat None as valid input (hashes as "null").
+
+    Returns:
+        Hex-encoded hash digest string.
+
+    Raises:
+        ValueError: If payload exceeds MAX_HASH_INPUT_BYTES (10MB).
+    """
+    payload: bytes
+    if none_as_valid and obj is None:
+        payload = b"null"
+    elif isinstance(obj, bytes):
+        payload = obj
+    elif isinstance(obj, str):
+        payload = obj.encode()
+    else:
+        payload = json_dumpb(obj, sort_keys=True, deterministic_sets=True)
+
+    if len(payload) > MAX_HASH_INPUT_BYTES:
+        raise ValueError(f"Payload {len(payload):,}B > {MAX_HASH_INPUT_BYTES:,}B limit")
+
+    hasher = algorithm.get_hasher()
+    return hasher(payload).hexdigest()
+
+
+def compute_chain_hash(
+    payload_hash: str,
+    previous_hash: str | None,
+    algorithm: HashAlgorithm = HashAlgorithm.SHA256,
+) -> str:
+    """Compute chain hash linking current entry to previous.
+
+    Formula: HASH("{payload_hash}:{previous_hash or 'GENESIS'}")
+
+    Args:
+        payload_hash: Hash of current entry's payload.
+        previous_hash: Hash of previous entry (None for genesis entry).
+        algorithm: Hash algorithm to use.
+
+    Returns:
+        Hex-encoded chain hash for tamper-evident linking.
+    """
+    chain_input = f"{payload_hash}:{previous_hash or GENESIS_HASH}"
+    return compute_hash(chain_input, algorithm)