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

krons/core/__init__.py

@@ -1,55 +1,47 @@
 # 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."""
+"""Core module - Foundation primitives and submodules.
+
+Re-exports base classes from core/base/ and exposes submodules:
+- types: Sentinels, base types, DB types
+- specs: Spec definitions, Operable, adapters
+
+Note: Session (Message, Branch, Session, Exchange) is now at krons.session
+"""
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-# Lazy import mapping
+# Lazy import mapping - delegates to core.base
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
-    # broadcaster
-    "Broadcaster": ("krons.core.broadcaster", "Broadcaster"),
-    # element
-    "Element": ("krons.core.element", "Element"),
-    # event
-    "Event": ("krons.core.event", "Event"),
-    "EventStatus": ("krons.core.event", "EventStatus"),
-    "Execution": ("krons.core.event", "Execution"),
-    # eventbus
-    "EventBus": ("krons.core.eventbus", "EventBus"),
-    "Handler": ("krons.core.eventbus", "Handler"),
-    # flow
-    "Flow": ("krons.core.flow", "Flow"),
-    # graph
-    "Edge": ("krons.core.graph", "Edge"),
-    "EdgeCondition": ("krons.core.graph", "EdgeCondition"),
-    "Graph": ("krons.core.graph", "Graph"),
-    # node
-    "DEFAULT_NODE_CONFIG": ("krons.core.node", "DEFAULT_NODE_CONFIG"),
-    "NODE_REGISTRY": ("krons.core.node", "NODE_REGISTRY"),
-    "PERSISTABLE_NODE_REGISTRY": ("krons.core.node", "PERSISTABLE_NODE_REGISTRY"),
-    "Node": ("krons.core.node", "Node"),
-    "NodeConfig": ("krons.core.node", "NodeConfig"),
-    "create_node": ("krons.core.node", "create_node"),
-    "generate_ddl": ("krons.core.node", "generate_ddl"),
-    # phrase
-    "PHRASE_REGISTRY": ("krons.core.phrase", "PHRASE_REGISTRY"),
-    "Phrase": ("krons.core.phrase", "Phrase"),
-    "PhraseConfig": ("krons.core.phrase", "PhraseConfig"),
-    "PhraseError": ("krons.core.phrase", "PhraseError"),
-    "RequirementNotMet": ("krons.core.phrase", "RequirementNotMet"),
-    "create_phrase": ("krons.core.phrase", "create_phrase"),
-    "get_phrase": ("krons.core.phrase", "get_phrase"),
-    "list_phrases": ("krons.core.phrase", "list_phrases"),
-    # pile
-    "Pile": ("krons.core.pile", "Pile"),
-    # processor
-    "Executor": ("krons.core.processor", "Executor"),
-    "Processor": ("krons.core.processor", "Processor"),
-    # progression
-    "Progression": ("krons.core.progression", "Progression"),
+    # Registries
+    "NODE_REGISTRY": ("krons.core.base", "NODE_REGISTRY"),
+    "PERSISTABLE_NODE_REGISTRY": ("krons.core.base", "PERSISTABLE_NODE_REGISTRY"),
+    # Classes
+    "Broadcaster": ("krons.core.base", "Broadcaster"),
+    "Edge": ("krons.core.base", "Edge"),
+    "EdgeCondition": ("krons.core.base", "EdgeCondition"),
+    "Element": ("krons.core.base", "Element"),
+    "Event": ("krons.core.base", "Event"),
+    "EventBus": ("krons.core.base", "EventBus"),
+    "EventStatus": ("krons.core.base", "EventStatus"),
+    "Execution": ("krons.core.base", "Execution"),
+    "Executor": ("krons.core.base", "Executor"),
+    "Flow": ("krons.core.base", "Flow"),
+    "Graph": ("krons.core.base", "Graph"),
+    "Handler": ("krons.core.base", "Handler"),
+    "Node": ("krons.core.base", "Node"),
+    "NodeConfig": ("krons.core.base", "NodeConfig"),
+    "Pile": ("krons.core.base", "Pile"),
+    "Processor": ("krons.core.base", "Processor"),
+    "Progression": ("krons.core.base", "Progression"),
+    # Functions
+    "create_node": ("krons.core.base", "create_node"),
+    "generate_all_ddl": ("krons.core.base", "generate_all_ddl"),
+    "generate_ddl": ("krons.core.base", "generate_ddl"),
+    "get_fk_dependencies": ("krons.core.base", "get_fk_dependencies"),
 }
 
 _LOADED: dict[str, object] = {}
@@ -79,41 +71,36 @@ def __dir__() -> list[str]:
 
 # 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 (
-        DEFAULT_NODE_CONFIG,
+    from krons.core.base import (
         NODE_REGISTRY,
         PERSISTABLE_NODE_REGISTRY,
+        Broadcaster,
+        Edge,
+        EdgeCondition,
+        Element,
+        Event,
+        EventBus,
+        EventStatus,
+        Execution,
+        Executor,
+        Flow,
+        Graph,
+        Handler,
         Node,
         NodeConfig,
+        Pile,
+        Processor,
+        Progression,
         create_node,
+        generate_all_ddl,
         generate_ddl,
+        get_fk_dependencies,
     )
-    from .phrase import (
-        PHRASE_REGISTRY,
-        Phrase,
-        PhraseConfig,
-        PhraseError,
-        RequirementNotMet,
-        create_phrase,
-        get_phrase,
-        list_phrases,
-    )
-    from .pile import Pile
-    from .processor import Executor, Processor
-    from .progression import Progression
 
 __all__ = [
-    # constants
-    "DEFAULT_NODE_CONFIG",
+    # constants/registries
     "NODE_REGISTRY",
     "PERSISTABLE_NODE_REGISTRY",
-    "PHRASE_REGISTRY",
     # classes
     "Broadcaster",
     "Edge",
@@ -129,17 +116,12 @@ __all__ = [
     "Handler",
     "Node",
     "NodeConfig",
-    "Phrase",
-    "PhraseConfig",
-    "PhraseError",
     "Pile",
     "Processor",
     "Progression",
-    "RequirementNotMet",
     # functions
     "create_node",
-    "create_phrase",
+    "generate_all_ddl",
     "generate_ddl",
-    "get_phrase",
-    "list_phrases",
+    "get_fk_dependencies",
 ]

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",
+]

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

@@ -8,7 +8,7 @@ import weakref
 from collections.abc import Awaitable, Callable
 from typing import Any, ClassVar
 
-from krons.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:

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

@@ -11,6 +11,7 @@ from uuid import UUID, uuid4
 import orjson
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from krons.core.types import MaybeSentinel, Unset, UnsetType, is_sentinel, is_unset
 from krons.protocols import (
     Deserializable,
     Hashable,
@@ -18,7 +19,6 @@ from krons.protocols import (
     Serializable,
     implements,
 )
-from krons.types import MaybeSentinel, Unset, UnsetType, is_sentinel, is_unset
 from krons.utils import (
     coerce_created_at,
     json_dump,
@@ -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)

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

@@ -11,9 +11,16 @@ from typing import Any, final
 import orjson
 from pydantic import Field, field_serializer, field_validator
 
-from krons.errors import KronError, KronTimeoutError
+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.types import Enum, MaybeSentinel, MaybeUnset, Unset, is_sentinel, is_unset
 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,
+            )

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

@@ -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.

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

@@ -9,9 +9,9 @@ from uuid import UUID
 
 from pydantic import Field, PrivateAttr, field_validator, model_validator
 
+from krons.core.types import Unset, UnsetType
 from krons.errors import ExistsError, NotFoundError
 from krons.protocols import Serializable, implements
-from krons.types import Unset, UnsetType
 from krons.utils import extract_types, synchronized
 
 from .element import Element
@@ -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]:

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

@@ -11,9 +11,9 @@ from uuid import UUID
 from pydantic import Field, PrivateAttr, field_validator, model_validator
 from typing_extensions import override
 
+from krons.core.types import Unset, UnsetType, is_unset
 from krons.errors import NotFoundError
 from krons.protocols import Containable, Deserializable, Serializable, implements
-from krons.types import Unset, UnsetType, is_unset
 from krons.utils import synchronized
 
 from .element import Element
@@ -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.