lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/base/element.py

@@ -0,0 +1,300 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any, Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+from ..protocols import (
+    Deserializable,
+    Hashable,
+    Observable,
+    Serializable,
+    implements,
+)
+
+__all__ = ("DEFAULT_ELEMENT_SERIALIZER", "LN_ELEMENT_FIELDS", "Element")
+
+
+@implements(Observable, Serializable, Deserializable, Hashable)
+class Element(BaseModel):
+    """Base element with UUID identity, timestamps, polymorphic serialization.
+
+    Attributes:
+        id: UUID identifier (frozen, auto-generated)
+        created_at: UTC datetime (frozen, auto-generated)
+        metadata: Arbitrary metadata dict
+
+    Serialization injects lion_class for polymorphic deserialization.
+    """
+
+    id: UUID = Field(default_factory=uuid4, frozen=True)
+    created_at: dt.datetime = Field(default_factory=lambda: dt.datetime.now(dt.UTC), frozen=True)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+        "validate_assignment": True,
+        "use_enum_values": True,
+        "extra": "forbid",
+    }
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _coerce_id(cls, v) -> UUID:
+        """Coerce to UUID4."""
+        from ._utils import to_uuid
+
+        return to_uuid(v)
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def _coerce_created_at(cls, v) -> dt.datetime:
+        """Coerce to UTC datetime."""
+        from ._utils import coerce_created_at
+
+        return coerce_created_at(v)
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _validate_meta_integrity(cls, val: dict[str, Any] | None) -> dict[str, Any]:
+        """Validate and coerce metadata to dict. Raises ValueError if conversion fails."""
+        if not val:
+            return {}
+
+        if not isinstance(val, dict):
+            from lionherd_core.ln import to_dict
+
+            val = to_dict(val, recursive=True, suppress=True)
+
+        if not isinstance(val, dict):
+            raise ValueError("Invalid metadata: must be a dictionary")
+
+        return val
+
+    @classmethod
+    def class_name(cls, full: bool = False) -> str:
+        """Returns this class's name, stripping generic type parameters.
+
+        For generic classes (e.g., Flow[Item, Prog]), returns the origin class name
+        without type parameters (e.g., Flow).
+
+        Args:
+            full: If True, returns fully qualified name (module.Class); otherwise class name only
+
+        Returns:
+            Class name string without generic parameters
+
+        Note:
+            For Pydantic generic models, runtime classes have type parameters in __name__.
+            We strip these using string parsing since typing.get_origin() doesn't work
+            on Pydantic runtime instances.
+        """
+        # For Pydantic generic models, __name__ and __qualname__ include type params at runtime
+        # e.g., "Flow[Item, Prog]" instead of "Flow"
+        name = cls.__qualname__ if full else cls.__name__
+
+        # Strip generic type parameters (Flow[E, P] -> Flow)
+        if "[" in name:
+            name = name.split("[")[0]
+
+        if full:
+            return f"{cls.__module__}.{name}"
+        return name
+
+    def _to_dict(self, **kwargs: Any) -> dict[str, Any]:
+        """Serialize to dict with lion_class injected in metadata."""
+        data = self.model_dump(**kwargs)
+
+        # Inject lion_class for polymorphic deserialization, if not explicitly excluded
+        if "metadata" in data:
+            data["metadata"]["lion_class"] = self.__class__.class_name(full=True)
+
+        return data
+
+    def to_dict(
+        self,
+        mode: Literal["python", "json", "db"] = "python",
+        created_at_format: Literal["datetime", "isoformat", "timestamp"] | None = None,
+        meta_key: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Serialize to dict with lion_class metadata.
+
+        Args:
+            mode: python/json/db (db auto-renames metadata to node_metadata)
+            created_at_format: datetime/isoformat/timestamp (auto-selected by mode)
+            meta_key: Rename metadata field (overrides db default)
+            **kwargs: Passed to model_dump()
+        """
+        if created_at_format is None:
+            created_at_format = "isoformat" if mode in ("json", "db") else "datetime"
+
+        if meta_key is None and mode == "db":
+            meta_key = "node_metadata"
+
+        if mode == "python":
+            data = self._to_dict(**kwargs)
+        elif mode in ("json", "db"):
+            import orjson
+
+            kwargs.pop("mode", None)  # Avoid recursion
+            json_bytes = self.to_json(decode=False, **kwargs)
+            data = orjson.loads(json_bytes)
+        else:
+            raise ValueError(f"Invalid mode: {mode}. Must be 'python', 'json', or 'db'")
+
+        if "created_at" in data and mode == "python":
+            if created_at_format == "isoformat":
+                data["created_at"] = self.created_at.isoformat()
+            elif created_at_format == "timestamp":
+                data["created_at"] = self.created_at.timestamp()
+            # "datetime" is default for python mode, already in correct format
+
+        # Rename metadata key if specified (works with any mode)
+        if meta_key and "metadata" in data:
+            data[meta_key] = data.pop("metadata")
+
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], meta_key: str | None = None, **kwargs: Any) -> Element:
+        """Deserialize from dict with polymorphic type restoration via lion_class.
+
+        Args:
+            data: Serialized element dict
+            meta_key: Restore metadata from this key (db mode compatibility)
+            **kwargs: Passed to model_validate()
+
+        Raises:
+            ValueError: If lion_class invalid or not Element subclass
+        """
+        data = data.copy()  # avoid mutating input
+
+        # Restore metadata from custom key if specified (db mode deserialization)
+        if meta_key and meta_key in data:
+            data["metadata"] = data.pop(meta_key)
+        elif "node_metadata" in data and "metadata" not in data:  # backward compatibility
+            data["metadata"] = data.pop("node_metadata")
+
+        data.pop("node_metadata", None)  # remove legacy key if present
+
+        # Extract and remove lion_class from metadata (serialization-only metadata)
+        metadata = data.get("metadata", {})
+        if isinstance(metadata, dict):
+            metadata = metadata.copy()
+            data["metadata"] = metadata
+            lion_class = metadata.pop("lion_class", None)
+        else:
+            lion_class = None
+
+        if lion_class and lion_class != cls.class_name(full=True):
+            from ._utils import load_type_from_string  # Dynamic import to load the target class
+
+            try:
+                target_cls = load_type_from_string(lion_class)
+            except ValueError as e:
+                raise ValueError(f"Failed to deserialize class '{lion_class}': {e}") from e
+
+            if not issubclass(target_cls, Element):
+                raise ValueError(
+                    f"'{lion_class}' is not an Element subclass. "
+                    f"Cannot deserialize into {cls.__name__}"
+                )
+
+            # Polymorphic deserialization requires from_dict
+            if not hasattr(target_cls, "from_dict") or not callable(
+                getattr(target_cls, "from_dict", None)
+            ):
+                raise ValueError(
+                    f"'{lion_class}' does not implement from_dict(). "
+                    f"Cannot perform polymorphic deserialization"
+                )
+
+            # Prevent infinite recursion: check if target has different from_dict implementation
+            # Use getattr to safely access __func__ (classmethods have it, but type system doesn't guarantee)
+            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)
+
+            # Delegate to target class's from_dict (different implementation)
+            return target_cls.from_dict(data, **kwargs)
+
+        return cls.model_validate(data, **kwargs)
+
+    @classmethod
+    def from_json(cls, json_str: str, /, **kwargs: Any) -> Element:
+        """Create from JSON string."""
+        import orjson
+
+        return cls.from_dict(orjson.loads(json_str), **kwargs)
+
+    def to_json(
+        self,
+        *,
+        pretty: bool = False,
+        sort_keys: bool = False,
+        decode: bool = True,
+        **kwargs: Any,
+    ) -> str | bytes:
+        """Serialize to JSON with nested Element/BaseModel support.
+
+        Args:
+            pretty: Indent output
+            sort_keys: Sort dict keys
+            decode: Return str (True) or bytes (False)
+            **kwargs: Passed to model_dump()
+        """
+        from lionherd_core.ln import json_dumps
+
+        # Get dict with lion_class metadata (python mode for nested object handling)
+        data = self._to_dict(**kwargs)
+
+        return json_dumps(
+            data,
+            default=_get_default_serializer(),
+            pretty=pretty,
+            sort_keys=sort_keys,
+            decode=decode,
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        """Elements are equal if they have the same ID."""
+        if not isinstance(other, Element):
+            return NotImplemented
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        """Hash by ID for use in sets/dicts."""
+        return hash(self.id)
+
+    def __bool__(self) -> bool:
+        """Elements are always truthy."""
+        return True
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id={self.id})"
+
+
+LN_ELEMENT_FIELDS = frozenset(("id", "created_at", "metadata"))
+DEFAULT_ELEMENT_SERIALIZER = None
+
+
+def _get_default_serializer():
+    """Get or create default orjson serializer (lazy init to avoid circular imports)."""
+    global DEFAULT_ELEMENT_SERIALIZER
+
+    if DEFAULT_ELEMENT_SERIALIZER is None:
+        from lionherd_core.ln import get_orjson_default
+
+        from ._utils import get_element_serializer_config
+
+        order, additional = get_element_serializer_config()
+        DEFAULT_ELEMENT_SERIALIZER = get_orjson_default(order=order, additional=additional)
+
+    return DEFAULT_ELEMENT_SERIALIZER

lionherd_core/base/event.py

@@ -0,0 +1,322 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, final
+
+from pydantic import Field, field_serializer, field_validator
+
+from ..errors import TimeoutError as LionherdTimeoutError
+from ..libs.concurrency import Lock
+from ..protocols import Invocable, Serializable, implements
+from ..types import Enum, MaybeSentinel, MaybeUnset, Unset, is_sentinel
+from ._utils import async_synchronized
+from .element import LN_ELEMENT_FIELDS, Element
+
+__all__ = (
+    "Event",
+    "EventStatus",
+    "Execution",
+)
+
+
+class EventStatus(Enum):
+    """Event execution status states.
+
+    Values:
+        PENDING: Not yet started
+        PROCESSING: Currently executing
+        COMPLETED: Finished successfully
+        FAILED: Execution failed with error
+        CANCELLED: Interrupted by timeout or cancellation
+        SKIPPED: Bypassed due to condition
+        ABORTED: Pre-validation rejected, never started
+    """
+
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    SKIPPED = "skipped"
+    ABORTED = "aborted"
+
+
+@implements(Serializable)
+@dataclass(slots=True)
+class Execution:
+    """Execution state (status, duration, response, error, retryable).
+
+    Attributes:
+        status: Current execution status
+        duration: Elapsed time in seconds (Unset until complete)
+        response: Result (Unset if unavailable, None if legitimate null)
+        error: Exception if failed (Unset/None/BaseException)
+        retryable: Whether retry is safe (Unset/bool)
+    """
+
+    status: EventStatus = EventStatus.PENDING
+    duration: MaybeUnset[float] = Unset
+    response: MaybeSentinel[Any] = Unset
+    error: MaybeUnset[BaseException] | None = Unset
+    retryable: MaybeUnset[bool] = Unset
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dict with sentinel handling."""
+        from ._utils import get_json_serializable
+
+        if is_sentinel(self.response):
+            res_ = None
+        else:
+            res_ = get_json_serializable(self.response)
+            if res_ is Unset:
+                res_ = "<unserializable>"
+
+        error_dict = None
+        if self.error is not Unset and self.error is not None:
+            from lionherd_core.errors import LionherdError
+
+            if isinstance(self.error, LionherdError):
+                error_dict = self.error.to_dict()
+            elif isinstance(self.error, ExceptionGroup):
+                error_dict = self._serialize_exception_group(self.error)
+            else:
+                error_dict = {
+                    "error": type(self.error).__name__,
+                    "message": str(self.error),
+                }
+
+        duration_value = None if self.duration is Unset else self.duration
+        retryable_value = None if self.retryable is Unset else self.retryable
+
+        return {
+            "status": self.status.value,
+            "duration": duration_value,
+            "response": res_,
+            "error": error_dict,
+            "retryable": retryable_value,
+        }
+
+    def _serialize_exception_group(self, eg: ExceptionGroup) -> dict[str, Any]:
+        """Recursively serialize ExceptionGroup and nested exceptions."""
+        from lionherd_core.errors import LionherdError
+
+        exceptions = []
+        for exc in eg.exceptions:
+            if isinstance(exc, LionherdError):
+                exceptions.append(exc.to_dict())
+            elif isinstance(exc, ExceptionGroup):
+                exceptions.append(self._serialize_exception_group(exc))
+            else:
+                exceptions.append(
+                    {
+                        "error": type(exc).__name__,
+                        "message": str(exc),
+                    }
+                )
+
+        return {
+            "error": type(eg).__name__,
+            "message": str(eg),
+            "exceptions": exceptions,
+        }
+
+    def add_error(self, exc: BaseException) -> None:
+        """Add error to execution. Creates ExceptionGroup if multiple errors."""
+        if self.error is Unset or self.error is None:
+            self.error = exc
+        elif isinstance(self.error, ExceptionGroup):
+            # Already have group - extend it
+            self.error = ExceptionGroup(  # type: ignore[type-var]
+                "multiple errors",
+                [*self.error.exceptions, exc],
+            )
+        else:
+            self.error = ExceptionGroup(  # type: ignore[type-var]
+                "multiple errors",
+                [self.error, exc],
+            )
+
+
+@implements(Invocable)
+class Event(Element):
+    """Base event with lifecycle tracking and execution state.
+
+    Subclasses implement _invoke(). invoke() manages transitions, timing, errors.
+
+    Attributes:
+        execution: Execution state
+        timeout: Optional timeout in seconds (None = no timeout)
+    """
+
+    execution: Execution = Field(default_factory=Execution)
+    timeout: float | None = Field(None, exclude=True)
+
+    def model_post_init(self, __context) -> None:
+        """Initialize async lock for thread-safe invoke()."""
+        super().model_post_init(__context)
+        self._async_lock = Lock()
+
+    @field_validator("timeout")
+    @classmethod
+    def _validate_timeout(cls, v: float | None) -> float | None:
+        """Validate timeout is positive and finite (raises ValueError if not)."""
+        if v is not None:
+            if not math.isfinite(v):
+                raise ValueError(f"timeout must be finite, got {v}")
+            if v <= 0:
+                raise ValueError(f"timeout must be positive, got {v}")
+        return v
+
+    @field_serializer("execution")
+    def _serialize_execution(self, val: Execution) -> dict:
+        """Serialize Execution to dict."""
+        return val.to_dict()
+
+    @property
+    def request(self) -> dict:
+        """Get request info."""
+        return {}
+
+    @property
+    def status(self) -> EventStatus:
+        """Get execution status."""
+        return self.execution.status
+
+    @status.setter
+    def status(self, val: EventStatus | str) -> None:
+        """Set execution status."""
+        if isinstance(val, str):
+            val = EventStatus(val)
+        elif not isinstance(val, EventStatus):
+            raise ValueError(f"Invalid status type: {type(val).__name__}")
+        self.execution.status = val
+
+    @property
+    def response(self) -> Any:
+        """Get execution response (read-only)."""
+        return self.execution.response
+
+    async def _invoke(self) -> Any:
+        """Execute event. Override in subclasses."""
+        raise NotImplementedError("Subclasses must implement _invoke()")
+
+    @final
+    @async_synchronized
+    async def invoke(self) -> Any:
+        """Execute with status tracking, timing, error capture (idempotent).
+
+        **Idempotency**: Multiple concurrent calls execute _invoke() exactly once.
+        Subsequent calls return cached result without re-execution. Once COMPLETED
+        or FAILED, invoke() will return the cached response.
+
+        **Retry Pattern**: To retry after FAILED status, use `as_fresh_event()` to
+        create a new Event with reset execution state. Direct invoke() calls on
+        completed events always return cached results.
+
+        Returns:
+            Execution result (same for all concurrent callers)
+        """
+        from lionherd_core.libs.concurrency import current_time
+
+        # Idempotency: Return cached result if already executed
+        if self.execution.status != EventStatus.PENDING:
+            return self.execution.response
+
+        start = current_time()
+
+        try:
+            self.execution.status = EventStatus.PROCESSING
+
+            if self.timeout is not None:
+                from lionherd_core.libs.concurrency import fail_after
+
+                with fail_after(self.timeout):
+                    result = await self._invoke()
+            else:
+                result = await self._invoke()
+
+            # Success path
+            self.execution.response = result
+            self.execution.error = None
+            self.execution.status = EventStatus.COMPLETED
+            self.execution.retryable = False
+            return result
+
+        except TimeoutError:
+            lionherd_timeout = LionherdTimeoutError(
+                f"Operation timed out after {self.timeout}s",
+                retryable=True,
+            )
+
+            self.execution.response = Unset
+            self.execution.error = lionherd_timeout
+            self.execution.status = EventStatus.CANCELLED
+            self.execution.retryable = lionherd_timeout.retryable
+            return None
+
+        except Exception as e:
+            from lionherd_core.errors import LionherdError
+
+            if isinstance(e, ExceptionGroup):
+                # All exceptions must be retryable for group to be retryable
+                retryable = True
+                for exc in e.exceptions:
+                    if isinstance(exc, LionherdError) and not exc.retryable:
+                        retryable = False
+                        break
+
+                self.execution.retryable = retryable
+            else:
+                if isinstance(e, LionherdError):
+                    self.execution.retryable = e.retryable
+                else:
+                    self.execution.retryable = True
+
+            self.execution.response = Unset
+            self.execution.error = e
+            self.execution.status = EventStatus.FAILED
+            return None
+
+        except BaseException as e:
+            from lionherd_core.libs.concurrency import get_cancelled_exc_class
+
+            if isinstance(e, get_cancelled_exc_class()):
+                self.execution.response = Unset
+                self.execution.error = e
+                self.execution.status = EventStatus.CANCELLED
+                self.execution.retryable = True
+
+            raise
+
+        finally:
+            self.execution.duration = current_time() - start
+
+    async def stream(self) -> Any:
+        """Stream execution. Override if supported."""
+        raise NotImplementedError("Subclasses must implement stream() if streaming=True")
+
+    def as_fresh_event(self, copy_meta: bool = False) -> Event:
+        """Clone with reset execution (fresh ID, PENDING status)."""
+        d_ = self.to_dict()
+        for key in ["execution", *LN_ELEMENT_FIELDS]:
+            d_.pop(key, None)
+
+        fresh = self.__class__(**d_)
+
+        if hasattr(self, "timeout") and self.timeout is not None:
+            fresh.timeout = self.timeout
+
+        if copy_meta and hasattr(self, "metadata"):
+            fresh.metadata = self.metadata.copy()
+
+        if hasattr(fresh, "metadata"):
+            fresh.metadata["original"] = {
+                "id": str(self.id),
+                "created_at": self.created_at,
+            }
+
+        return fresh