krons 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

krons/core/base/__init__.py

@@ -0,0 +1,121 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Core primitives with lazy loading for fast import."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy import mapping - all modules are in krons.core.base.*
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # broadcaster
+    "Broadcaster": ("krons.core.base.broadcaster", "Broadcaster"),
+    # element
+    "Element": ("krons.core.base.element", "Element"),
+    # event
+    "Event": ("krons.core.base.event", "Event"),
+    "EventStatus": ("krons.core.base.event", "EventStatus"),
+    "Execution": ("krons.core.base.event", "Execution"),
+    # eventbus
+    "EventBus": ("krons.core.base.eventbus", "EventBus"),
+    "Handler": ("krons.core.base.eventbus", "Handler"),
+    # flow
+    "Flow": ("krons.core.base.flow", "Flow"),
+    # graph
+    "Edge": ("krons.core.base.graph", "Edge"),
+    "EdgeCondition": ("krons.core.base.graph", "EdgeCondition"),
+    "Graph": ("krons.core.base.graph", "Graph"),
+    # node
+    "NODE_REGISTRY": ("krons.core.base.node", "NODE_REGISTRY"),
+    "PERSISTABLE_NODE_REGISTRY": ("krons.core.base.node", "PERSISTABLE_NODE_REGISTRY"),
+    "Node": ("krons.core.base.node", "Node"),
+    "NodeConfig": ("krons.core.base.node", "NodeConfig"),
+    "create_node": ("krons.core.base.node", "create_node"),
+    "generate_ddl": ("krons.core.base.node", "generate_ddl"),
+    "generate_all_ddl": ("krons.core.base.node", "generate_all_ddl"),
+    "get_fk_dependencies": ("krons.core.base.node", "get_fk_dependencies"),
+    # pile
+    "Pile": ("krons.core.base.pile", "Pile"),
+    # processor
+    "Executor": ("krons.core.base.processor", "Executor"),
+    "Processor": ("krons.core.base.processor", "Processor"),
+    # progression
+    "Progression": ("krons.core.base.progression", "Progression"),
+}
+
+_LOADED: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import attributes on first access."""
+    if name in _LOADED:
+        return _LOADED[name]
+
+    if name in _LAZY_IMPORTS:
+        from importlib import import_module
+
+        module_name, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_name)
+        value = getattr(module, attr_name)
+        _LOADED[name] = value
+        return value
+
+    raise AttributeError(f"module 'krons.core' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all available attributes for autocomplete."""
+    return list(__all__)
+
+
+# TYPE_CHECKING block for static analysis
+if TYPE_CHECKING:
+    from .broadcaster import Broadcaster
+    from .element import Element
+    from .event import Event, EventStatus, Execution
+    from .eventbus import EventBus, Handler
+    from .flow import Flow
+    from .graph import Edge, EdgeCondition, Graph
+    from .node import (
+        NODE_REGISTRY,
+        PERSISTABLE_NODE_REGISTRY,
+        Node,
+        NodeConfig,
+        create_node,
+        generate_all_ddl,
+        generate_ddl,
+        get_fk_dependencies,
+    )
+    from .pile import Pile
+    from .processor import Executor, Processor
+    from .progression import Progression
+
+__all__ = [
+    # constants/registries
+    "NODE_REGISTRY",
+    "PERSISTABLE_NODE_REGISTRY",
+    # classes
+    "Broadcaster",
+    "Edge",
+    "EdgeCondition",
+    "Element",
+    "Event",
+    "EventBus",
+    "EventStatus",
+    "Execution",
+    "Executor",
+    "Flow",
+    "Graph",
+    "Handler",
+    "Node",
+    "NodeConfig",
+    "Pile",
+    "Processor",
+    "Progression",
+    # functions
+    "create_node",
+    "generate_all_ddl",
+    "generate_ddl",
+    "get_fk_dependencies",
+]

{kronos/core → krons/core/base}/broadcaster.py

@@ -8,7 +8,7 @@ import weakref
 from collections.abc import Awaitable, Callable
 from typing import Any, ClassVar
 
-from kronos.utils import is_coro_func
+from krons.utils.concurrency import is_coro_func
 
 logger = logging.getLogger(__name__)
 
@@ -41,7 +41,9 @@ class Broadcaster:
         return cls._instance
 
     @classmethod
-    def subscribe(cls, callback: Callable[[Any], None] | Callable[[Any], Awaitable[None]]) -> None:
+    def subscribe(
+        cls, callback: Callable[[Any], None] | Callable[[Any], Awaitable[None]]
+    ) -> None:
         """Add subscriber callback (idempotent, stored as weakref).
 
         Args:
@@ -51,7 +53,9 @@ class Broadcaster:
         for weak_ref in cls._subscribers:
             if weak_ref() is callback:
                 return
-        weak_callback: weakref.ref[Callable[[Any], None] | Callable[[Any], Awaitable[None]]]
+        weak_callback: weakref.ref[
+            Callable[[Any], None] | Callable[[Any], Awaitable[None]]
+        ]
         if hasattr(callback, "__self__"):
             weak_callback = weakref.WeakMethod(callback)  # type: ignore[assignment]
         else:

{kronos/core → krons/core/base}/element.py

@@ -11,15 +11,15 @@ from uuid import UUID, uuid4
 import orjson
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
-from kronos.protocols import (
+from krons.core.types import MaybeSentinel, Unset, UnsetType, is_sentinel, is_unset
+from krons.protocols import (
     Deserializable,
     Hashable,
     Observable,
     Serializable,
     implements,
 )
-from kronos.types import MaybeSentinel, Unset, UnsetType, is_sentinel, is_unset
-from kronos.utils import (
+from krons.utils import (
     coerce_created_at,
     json_dump,
     load_type_from_string,
@@ -68,7 +68,9 @@ class Element(BaseModel):
 
     @field_validator("metadata", mode="before")
     @classmethod
-    def _validate_meta_integrity(cls, val: dict[str, Any] | MaybeSentinel) -> dict[str, Any]:
+    def _validate_meta_integrity(
+        cls, val: dict[str, Any] | MaybeSentinel
+    ) -> dict[str, Any]:
         """Validate and coerce metadata to dict. Raises ValueError if conversion fails."""
         if is_sentinel(val, {"none"}):
             return {}
@@ -108,7 +110,9 @@ class Element(BaseModel):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         **kwargs: Any,
     ) -> dict[str, Any]:
@@ -187,7 +191,9 @@ class Element(BaseModel):
             try:
                 target_cls = load_type_from_string(kron_class)
             except ValueError as e:
-                raise ValueError(f"Failed to deserialize class '{kron_class}': {e}") from e
+                raise ValueError(
+                    f"Failed to deserialize class '{kron_class}': {e}"
+                ) from e
 
             if not issubclass(target_cls, Element):
                 raise ValueError(
@@ -195,7 +201,9 @@ class Element(BaseModel):
                     f"Cannot deserialize into {cls.__name__}"
                 )
 
-            target_func = getattr(target_cls.from_dict, "__func__", target_cls.from_dict)
+            target_func = getattr(
+                target_cls.from_dict, "__func__", target_cls.from_dict
+            )
             cls_func = getattr(cls.from_dict, "__func__", cls.from_dict)
             if target_func is cls_func:
                 return target_cls.model_validate(data, **kwargs)

{kronos/core → krons/core/base}/event.py

@@ -11,10 +11,17 @@ from typing import Any, final
 import orjson
 from pydantic import Field, field_serializer, field_validator
 
-from kronos.errors import KronError, KronTimeoutError
-from kronos.protocols import Invocable, Serializable, implements
-from kronos.types import Enum, MaybeSentinel, MaybeUnset, Unset, is_sentinel, is_unset
-from kronos.utils import async_synchronized, concurrency, json_dumpb
+from krons.core.types import (
+    Enum,
+    MaybeSentinel,
+    MaybeUnset,
+    Unset,
+    is_sentinel,
+    is_unset,
+)
+from krons.errors import KronsError, KronTimeoutError, ValidationError
+from krons.protocols import Invocable, Serializable, implements
+from krons.utils import async_synchronized, concurrency, json_dumpb
 
 from .element import LN_ELEMENT_FIELDS, Element
 
@@ -142,7 +149,9 @@ class Execution:
                 if isinstance(exc, Serializable):
                     exceptions.append(exc.to_dict())
                 elif isinstance(exc, ExceptionGroup):
-                    exceptions.append(self._serialize_exception_group(exc, depth + 1, _seen))
+                    exceptions.append(
+                        self._serialize_exception_group(exc, depth + 1, _seen)
+                    )
                 else:
                     exceptions.append(
                         {
@@ -262,11 +271,14 @@ class Event(Element):
         except Exception as e:
             if isinstance(e, ExceptionGroup):
                 retryable = all(
-                    not isinstance(exc, KronError) or exc.retryable for exc in e.exceptions
+                    not isinstance(exc, KronsError) or exc.retryable
+                    for exc in e.exceptions
                 )
                 self.execution.retryable = retryable
             else:
-                self.execution.retryable = e.retryable if isinstance(e, KronError) else True
+                self.execution.retryable = (
+                    e.retryable if isinstance(e, KronsError) else True
+                )
 
             self.execution.response = Unset
             self.execution.error = e
@@ -286,7 +298,9 @@ class Event(Element):
 
     async def stream(self) -> Any:
         """Stream execution results. Override if streaming=True."""
-        raise NotImplementedError("Subclasses must implement stream() if streaming=True")
+        raise NotImplementedError(
+            "Subclasses must implement stream() if streaming=True"
+        )
 
     def as_fresh_event(self, copy_meta: bool = False) -> Event:
         """Clone with reset execution state (new ID, PENDING status).
@@ -314,3 +328,22 @@ class Event(Element):
             "created_at": self.created_at,
         }
         return fresh
+
+    def assert_completed(self, *, retryable: MaybeUnset[bool] = Unset):
+        if self.execution.status != EventStatus.COMPLETED:
+            retryable_value = (
+                self.execution.retryable if is_unset(retryable) else retryable
+            )
+            retryable_value = True if retryable_value is True else False
+            exec_dict = self.execution.to_dict()
+            exec_dict.pop("response", None)
+            exec_dict.pop("retryable", None)
+
+            raise ValidationError(
+                "Event did not complete successfully.",
+                details={
+                    "event_id": str(self.id),
+                    **exec_dict,
+                },
+                retryable=retryable_value,
+            )

{kronos/core → krons/core/base}/eventbus.py

@@ -8,7 +8,7 @@ from collections import defaultdict
 from collections.abc import Awaitable, Callable
 from typing import Any
 
-from kronos.utils.concurrency import gather
+from krons.utils.concurrency import gather
 
 __all__ = ("EventBus", "Handler")
 
@@ -85,7 +85,9 @@ class EventBus:
         if topic not in self._subs:
             return
         if handlers := self._cleanup_dead_refs(topic):
-            await gather(*(h(*args, **kwargs) for h in handlers), return_exceptions=True)
+            await gather(
+                *(h(*args, **kwargs) for h in handlers), return_exceptions=True
+            )
 
     def clear(self, topic: str | None = None) -> None:
         """Clear subscriptions.

{kronos/core → krons/core/base}/flow.py

@@ -9,10 +9,10 @@ from uuid import UUID
 
 from pydantic import Field, PrivateAttr, field_validator, model_validator
 
-from kronos.errors import ExistsError, NotFoundError
-from kronos.protocols import Serializable, implements
-from kronos.types import Unset, UnsetType
-from kronos.utils import extract_types, synchronized
+from krons.core.types import Unset, UnsetType
+from krons.errors import ExistsError, NotFoundError
+from krons.protocols import Serializable, implements
+from krons.utils import extract_types, synchronized
 
 from .element import Element
 from .pile import Pile
@@ -99,7 +99,9 @@ class Flow(Element, Generic[E, P]):
 
             # Create Pile with items and type validation (item_type/strict_type are frozen)
             # Even if items=None, create Pile if item_type/strict_type specified
-            data["items"] = Pile(items=items, item_type=item_type, strict_type=strict_type)
+            data["items"] = Pile(
+                items=items, item_type=item_type, strict_type=strict_type
+            )
 
         # Handle progressions - let field validator convert dict/list to Pile
         if progressions is not None:
@@ -217,7 +219,10 @@ class Flow(Element, Generic[E, P]):
             NotFoundError: If progression not found.
         """
         name_to_delete: str | None
-        if isinstance(progression_id, str) and progression_id in self._progression_names:
+        if (
+            isinstance(progression_id, str)
+            and progression_id in self._progression_names
+        ):
             uid = self._progression_names[progression_id]
             name_to_delete = progression_id
         else:
@@ -323,7 +328,9 @@ class Flow(Element, Generic[E, P]):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         **kwargs: Any,
     ) -> dict[str, Any]:

{kronos/core → krons/core/base}/graph.py

@@ -11,10 +11,10 @@ from uuid import UUID
 from pydantic import Field, PrivateAttr, field_validator, model_validator
 from typing_extensions import override
 
-from kronos.errors import NotFoundError
-from kronos.protocols import Containable, Deserializable, Serializable, implements
-from kronos.types import Unset, UnsetType, is_unset
-from kronos.utils import synchronized
+from krons.core.types import Unset, UnsetType, is_unset
+from krons.errors import NotFoundError
+from krons.protocols import Containable, Deserializable, Serializable, implements
+from krons.utils import synchronized
 
 from .element import Element
 from .node import Node
@@ -61,7 +61,9 @@ class Edge(Element):
     condition: EdgeCondition | None = Field(
         default=None, exclude=True, description="Runtime traversal predicate"
     )
-    properties: dict[str, Any] = Field(default_factory=dict, description="Custom edge attributes")
+    properties: dict[str, Any] = Field(
+        default_factory=dict, description="Custom edge attributes"
+    )
 
     @field_validator("head", "tail", mode="before")
     @classmethod
@@ -212,12 +214,16 @@ class Graph(Element):
     def get_predecessors(self, node_id: UUID | Node) -> list[Node]:
         """Get nodes with edges pointing to this node (in-neighbors)."""
         nid = self._coerce_id(node_id)
-        return [self.nodes[self.edges[eid].head] for eid in self._in_edges.get(nid, set())]
+        return [
+            self.nodes[self.edges[eid].head] for eid in self._in_edges.get(nid, set())
+        ]
 
     def get_successors(self, node_id: UUID | Node) -> list[Node]:
         """Get nodes this node points to (out-neighbors)."""
         nid = self._coerce_id(node_id)
-        return [self.nodes[self.edges[eid].tail] for eid in self._out_edges.get(nid, set())]
+        return [
+            self.nodes[self.edges[eid].tail] for eid in self._out_edges.get(nid, set())
+        ]
 
     def get_node_edges(
         self,
@@ -240,11 +246,17 @@ class Graph(Element):
 
     def get_heads(self) -> list[Node]:
         """Get source nodes (no incoming edges)."""
-        return [self.nodes[nid] for nid, in_edges in self._in_edges.items() if not in_edges]
+        return [
+            self.nodes[nid] for nid, in_edges in self._in_edges.items() if not in_edges
+        ]
 
     def get_tails(self) -> list[Node]:
         """Get sink nodes (no outgoing edges)."""
-        return [self.nodes[nid] for nid, out_edges in self._out_edges.items() if not out_edges]
+        return [
+            self.nodes[nid]
+            for nid, out_edges in self._out_edges.items()
+            if not out_edges
+        ]
 
     # ==================== Graph Algorithms ====================
 
@@ -361,10 +373,14 @@ class Graph(Element):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         item_meta_key: str | UnsetType = Unset,
-        item_created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        item_created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """Serialize graph with nodes and edges as nested Pile dicts.

{kronos/core → krons/core/base}/node.py

@@ -15,8 +15,7 @@ from uuid import UUID
 
 from pydantic import BaseModel, field_serializer, field_validator
 
-from kronos.protocols import Deserializable, Serializable, implements
-from kronos.types import (
+from krons.core.types import (
     ModelConfig,
     Params,
     Unset,
@@ -25,8 +24,9 @@ from kronos.types import (
     is_unset,
     not_sentinel,
 )
-from kronos.types.db_types import VectorMeta, extract_kron_db_meta
-from kronos.utils import compute_hash, json_dump, now_utc
+from krons.core.types.db_types import VectorMeta, extract_kron_db_meta
+from krons.protocols import Deserializable, Serializable, implements
+from krons.utils import compute_hash, json_dump, now_utc
 
 from .element import Element
 
@@ -56,9 +56,13 @@ def _enable_embedding_requires_dim(config: NodeConfig) -> None:
     """Validate: embedding_enabled requires positive embedding_dim."""
     if config.embedding_enabled:
         if config.is_sentinel_field("embedding_dim"):
-            raise ValueError("embedding_dim must be specified when embedding is enabled")
+            raise ValueError(
+                "embedding_dim must be specified when embedding is enabled"
+            )
         if config.embedding_dim <= 0:
-            raise ValueError(f"embedding_dim must be positive, got {config.embedding_dim}")
+            raise ValueError(
+                f"embedding_dim must be positive, got {config.embedding_dim}"
+            )
 
 
 def _only_typed_content_can_flatten(config: NodeConfig) -> None:
@@ -231,7 +235,9 @@ class Node(Element):
                 cls._resolved_content_type = None
         else:
             cls._resolved_content_type = (
-                None if config.is_sentinel_field("content_type") else config.content_type
+                None
+                if config.is_sentinel_field("content_type")
+                else config.content_type
             )
 
     @field_serializer("content")
@@ -258,12 +264,15 @@ class Node(Element):
                 f"or Element.metadata for simple key-value pairs."
             )
 
-        # Polymorphic: restore type from kronos_class in metadata
+        # Polymorphic: restore type from krons_class in metadata
         if isinstance(value, dict) and "metadata" in value:
             metadata = value.get("metadata", {})
             kron_class = metadata.get("kron_class")
             if kron_class:
-                if kron_class in NODE_REGISTRY or kron_class.split(".")[-1] in NODE_REGISTRY:
+                if (
+                    kron_class in NODE_REGISTRY
+                    or kron_class.split(".")[-1] in NODE_REGISTRY
+                ):
                     return Node.from_dict(value)
                 return Element.from_dict(value)
         return value
@@ -271,7 +280,9 @@ class Node(Element):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         content_serializer: Callable[[Any], Any] | None = None,
         **kwargs: Any,
@@ -421,14 +432,18 @@ class Node(Element):
                 and issubclass(content_type, BaseModel)
             ):
                 content_field_names = set(content_type.model_fields.keys())
-                content_data = {k: v for k, v in data.items() if k in content_field_names}
+                content_data = {
+                    k: v for k, v in data.items() if k in content_field_names
+                }
                 for k in content_field_names:
                     data.pop(k, None)
                 data["content"] = content_type(**content_data)
 
         # Handle meta_key for DB rows
         effective_meta_key = (
-            meta_key if not is_unset(meta_key) else (config.meta_key if from_row else Unset)
+            meta_key
+            if not is_unset(meta_key)
+            else (config.meta_key if from_row else Unset)
         )
 
         if content_deserializer is not None:
@@ -503,7 +518,7 @@ class Node(Element):
             Computed integrity_hash, or None if integrity_hashing disabled
 
         """
-        from kronos.utils import compute_chain_hash
+        from krons.utils import compute_chain_hash
 
         config = self.get_config()
         if not config.integrity_hashing:
@@ -704,8 +719,8 @@ def create_node(
         >>> Job = create_node("Job", embedding_enabled=True, embedding_dim=1536)
 
     """
-    from kronos.specs.catalog import AuditSpecs, ContentSpecs
-    from kronos.specs.operable import Operable
+    from krons.core.specs.catalog import AuditSpecs, ContentSpecs
+    from krons.core.specs.operable import Operable
 
     # Resolve embedding dimension
     resolved_embedding_dim: int | UnsetType = Unset
@@ -723,7 +738,9 @@ def create_node(
             )
     elif embedding_enabled:
         if embedding_dim is None or embedding_dim <= 0:
-            raise ValueError("embedding_dim must be positive when embedding_enabled=True")
+            raise ValueError(
+                "embedding_dim must be positive when embedding_enabled=True"
+            )
         resolved_embedding_dim = embedding_dim
         has_embedding = True
 
@@ -742,7 +759,11 @@ def create_node(
         include.append("embedding")
 
     needs_update_tracking = (
-        track_updated_at or content_hashing or integrity_hashing or soft_delete or versioning
+        track_updated_at
+        or content_hashing
+        or integrity_hashing
+        or soft_delete
+        or versioning
     )
     if needs_update_tracking:
         include.append("updated_at")
@@ -805,7 +826,9 @@ def _extract_base_type(annotation: Any) -> Any:
     if annotation is None:
         return None
 
-    if isinstance(annotation, types.UnionType) or get_origin(annotation) is type(int | str):
+    if isinstance(annotation, types.UnionType) or get_origin(annotation) is type(
+        int | str
+    ):
         args = get_args(annotation)
         non_none_args = [a for a in args if a is not type(None)]
         if non_none_args:
@@ -835,12 +858,14 @@ def generate_ddl(
         ValueError: If node_cls has no table_name configured
 
     """
-    from kronos.specs.catalog import AuditSpecs, ContentSpecs
-    from kronos.specs.operable import Operable
+    from krons.core.specs.catalog import AuditSpecs, ContentSpecs
+    from krons.core.specs.operable import Operable
 
     config = node_cls.get_config()
     if not config.is_persisted:
-        raise ValueError(f"{node_cls.__name__} is not persistable (no table_name configured)")
+        raise ValueError(
+            f"{node_cls.__name__} is not persistable (no table_name configured)"
+        )
 
     # 1. Build all possible specs for this node
     content_type = (
@@ -855,7 +880,7 @@ def generate_ddl(
 
     # Flatten content: extract fields from BaseModel instead of generic JSONB
     if config.flatten_content and content_type is not None:
-        from kronos.specs.adapters.pydantic_adapter import PydanticSpecAdapter
+        from krons.core.specs.adapters.pydantic_adapter import PydanticSpecAdapter
 
         if isinstance(content_type, type) and issubclass(content_type, BaseModel):
             all_specs.extend(PydanticSpecAdapter.extract_specs(content_type))